Creative

TL;DR — Creatives feed đưa cho hệ thống marketing của bạn một bản ghi dữ liệu cho mỗi creative quảng cáo mà tổ chức của bạn đã duyệt trên Wandura: phim, các tập và cảnh được dùng, định dạng, thời lượng, hook, formula và ngày hết quyền của bạn. Bản ghi không bao giờ chứa URL media đã ký. Đồng bộ dần bằng updated_since và cursor. final.file_url của mỗi bản ghi là link chia sẻ công khai tới video cuối: không cần API key, nên đưa thẳng cho video upload của Meta được.

Feed chứa gì#

Các creative của tổ chức bạn có trạng thái approved hoặc pushed (đã giao). Bản nháp và creative của tổ chức khác không bao giờ xuất hiện. final.ready cho biết bản dựng cuối đã có chưa; có rồi thì tải về từ final.file_url.

Endpoint#

Cả ba cần key có creatives:export (Xác thực) và dùng chung một bộ đếm rate limit.

Envelope của response#

Response thành công được bọc trong một envelope:

{
  "code": 0,
  "message": "ok",
  "data": { "items": [], "next_cursor": null },
  "server_time": 1790679032
}

Lỗi dùng cùng envelope nhưng không có data (khi đó code là mã lỗi bốn chữ số), trừ 429 và 400 unsupported_version, hai lỗi này dùng định dạng phẳng. Timestamp trong feed này, kể cả server_time, tính bằng giây Unix epoch. Xem Lỗi.

Đồng bộ#

Bản ghi tới theo thứ tự cập nhật cũ nhất trước (theo updated_at, rồi theo ID), nên các cập nhật xảy ra trong lúc đồng bộ sẽ nằm sau các trang bạn đã đọc. Giữ một checkpoint (updated_at lớn nhất của lần chạy trọn vẹn gần nhất), gửi nó làm updated_since, lật trang bằng cursor, và ghi đè bản ghi theo creative_id: một bản ghi có thể tới hai lần. Quy trình đầy đủ và code: Đồng bộ creative.

Creative rời khỏi feed#

Không có sự kiện xoá. Creative không còn được duyệt thì thôi xuất hiện. Để kiểm tra một creative bạn đã lưu, gọi GET /creatives/{id}: 404 với code 4040 nghĩa là nó đã không còn.

Bản ghi#

Mọi trường: Liệt kê creative. Mỗi bản ghi mang schema_version (hiện là 1); trường mới được thêm mà không đổi số này, nên hãy bỏ qua các trường bạn không nhận ra.

Tải file cuối#

Khi final.ready là true, final.file_url là link chia sẻ của creative, ví dụ https://www.wandura.ai/api/c/Q3vh0xAbCdEfGhIjKlMnOpQrStUvWx9f.mp4. Link không cần API key. Mỗi lần mở trả 302 kèm link tải mới dùng được 15 phút, nên công cụ tải file bằng URL, như video upload của Meta (file_url), dùng thẳng được, dù khâu lên chiến dịch của bạn kéo dài bao lâu:

curl -sL -o final.mp4 "$FILE_URL"

• Lưu final.file_url, đừng lưu link tải mà nó chuyển tới: link tải hết hạn sau 15 phút, link chia sẻ thì không.
• Ai cầm link chia sẻ cũng tải được file. Giữ nó như mật khẩu: đừng công bố.
• Mỗi lần mở đều kiểm lại creative còn được duyệt và quyền xuất phim của bạn còn hiệu lực; không thì trả 410. Admin của tổ chức bạn thu hồi được link trên portal, và link trả 410 ngay.
• Sau khi thu hồi, final.file_url của bản ghi là null. Thu hồi không đổi updated_at, nên đồng bộ dần không thấy thay đổi này: khi một link đã lưu trả 410, gọi Lấy một creative để lấy link hiện tại. Vẫn null? Hỏi admin của bạn, hoặc tạo link chia sẻ mới trên portal.
• Mỗi link mở được 120 lần mỗi phút; quá mức đó trả 429 kèm Retry-After.
• File là MP4, 1080 × 1920: bản cuối sạch, có brand mark của công ty bạn nếu tổ chức bạn có.

Tải bằng API key#

GET /api/delivery/v1/creatives/{id}/file tải cùng file đó bằng API key thay cho link chia sẻ. Nó trả 302 kèm link tải dùng được 15 phút; phần lớn HTTP client tự đi theo:

curl -sL -o final.mp4 "https://www.wandura.ai/api/delivery/v1/creatives/$CREATIVE_ID/file" -H "Authorization: Bearer $WANDURA_API_KEY"

• 409 với code 4090 nghĩa là bản cuối chưa sẵn sàng. Sau khi quyền xuất của bạn hết, endpoint trả 403 với code 4032.
• Mỗi lần tải đều được ghi nhật ký theo API key của bạn. Lộ key thì thu hồi ngay: tới lúc đó, key tải được mọi bản cuối của tổ chức bạn.

Liên quan#

• Đồng bộ creative
• Khi quyền kết thúc