Liệt kê creative

Trả về một trang các creative đã duyệt của tổ chức bạn, mỗi creative là một bản ghi dữ liệu đầy đủ. Dùng endpoint này để đồng bộ creative vào hệ thống marketing, theo kiểu incremental với updated_since.

GET /api/delivery/v1/creatives

Scope: creatives:export

Mô tả

Trả về các creative của tổ chức bạn có status approved hoặc pushed, sắp theo updated_at tăng dần rồi theo ID. Bản ghi không bao giờ chứa URL media. Mọi response, dù thành công hay lỗi (trừ 429), đều được bọc trong envelope {code, message, data, server_time}. Xem Creative.

Tham số request

Tên	Vị trí	Kiểu	Bắt buộc	Mô tả
`Authorization`	header	string	Có	`Bearer <API key>` của một key có scope `creatives:export`.
`updated_since`	query	integer	Không	Giây Unix epoch (tối đa 11 chữ số). Chỉ trả về bản ghi có thời điểm cập nhật chính xác lớn hơn hẳn giây này (`>`, không phải `>=`).
`cursor`	query	string	Không	`next_cursor` của trang trước. Opaque; truyền lại nguyên vẹn.
`limit`	query	integer	Không	Số bản ghi mỗi trang, từ 1 đến 100. Mặc định `50`.

Bạn có thể kết hợp updated_since và cursor. Giữ nguyên updated_since trên mọi trang của cùng một lần đồng bộ. Vì updated_at trong mỗi bản ghi được làm tròn xuống theo giây, truyền updated_at lớn nhất bạn đã nhận thường trả lại vài bản ghi cuối; hãy ghi đè chúng theo creative_id.

Ví dụ request

curl -s "https://www.wandura.ai/api/delivery/v1/creatives?updated_since=1790600000&limit=2" \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Response

200 OK

Trường	Kiểu	Mô tả
`code`	integer	`0`.
`message`	string	`"ok"`.
`data.items`	array	Các bản ghi creative trên trang này. Xem Bản ghi creative.
`data.next_cursor`	string hoặc null	Truyền làm `cursor` để lấy trang kế tiếp. `null` ở trang cuối.
`server_time`	integer	Giờ server tính bằng giây Unix epoch.

Bản ghi creative

Lấy một creative trả về cùng bản ghi này.

Trường	Kiểu	Mô tả
`schema_version`	integer	Phiên bản schema của bản ghi. Hiện là `1`.
`creative_id`	string (UUID)	ID ổn định của creative.
`creative_code`	string hoặc null	Mã đọc được, không đổi. Coi nó là opaque.
`name`	string	Tên creative.
`status`	string	`approved`, hoặc `pushed` khi đã giao.
`created_at`	integer	Thời điểm tạo, giây Unix.
`approved_at`	integer hoặc null	Thời điểm duyệt, giây Unix.
`updated_at`	integer	Lần cập nhật gần nhất, giây Unix, làm tròn xuống.
`org.slug`	string	Slug của tổ chức bạn.
`film`	object hoặc null	Phim mà creative được cắt từ đó.
`film.code`	string hoặc null	Mã phim.
`film.title`	string hoặc null	Tên phim.
`film.language`	string hoặc null	Ngôn ngữ của phim.
`film.genres`	mảng string	Thể loại phim. Có thể rỗng.
`episodes`	mảng integer	Số thứ tự các tập được dùng, không trùng lặp.
`placement`	string hoặc null	`reels_9x16`, `feed_4x5` hoặc `square_1x1`.
`aspect`	string hoặc null	`9:16`, `4:5` hoặc `1:1`, khớp với `placement`.
`duration_ms`	integer	Tổng độ dài các clip phim được dùng, tính bằng mili giây.
`scenes`	array	Các clip phim được dùng, theo thứ tự.
`scenes[].episode_no`	integer hoặc null	Tập chứa clip.
`scenes[].start_ms`	integer	Điểm bắt đầu clip trong tập, mili giây.
`scenes[].end_ms`	integer	Điểm kết thúc clip trong tập, mili giây.
`scenes[].duration_ms`	integer	Độ dài clip, mili giây.
`scenes[].action`	string hoặc null	Nhãn hành động của cảnh, ví dụ `reveal`, `argue`, `slap`, `kiss`, `embrace`, `cry`, `kneel`, `walk_away` hoặc `violence`. `null` khi cảnh không có hành động đáng chú ý. Có thể có nhãn mới được thêm vào.
`scenes[].line`	string hoặc null	Câu thoại hoặc câu nổi bật của cảnh.
`hook`	object hoặc null	`action` và `line` của cảnh đầu tiên. `null` khi không có cảnh nào.
`formula`	object hoặc null	`{ "name": ... }` của formula dùng để dựng creative.
`rights.ends_at`	integer hoặc null	Ngày cuối cùng của quyền export phim, dạng giây Unix tại 00:00 UTC của ngày đó. Quyền của bạn gồm trọn ngày đó: ngừng dùng creative sau khi ngày UTC đó kết thúc, tức tại `ends_at + 86400`. `null` khi Wandura không có ngày kết thúc nào được ghi nhận cho quyền export của bạn.
`lineage.parent_creative_id`	string (UUID) hoặc null	Creative gốc mà creative này được phái sinh từ đó.
`final.ready`	boolean	Bản render hoàn chỉnh đã có hay chưa. Creative ở trạng thái `pushed` luôn đã có.
`final.target`	object	Thông số render đích: `width`, `height`, `fps`, `codec`. Hiện giống nhau cho mọi creative (1080 × 1920, 30 fps, `h264`) và không theo `placement`, nên đừng suy khung hình từ nó.

scenes chỉ liệt kê các clip lấy từ tập phim. Các thành phần khác của creative không được liệt kê, nên duration_ms có thể ngắn hơn video hoàn chỉnh.

Ví dụ response

{
  "code": 0,
  "message": "ok",
  "data": {
    "items": [
      {
        "schema_version": 1,
        "creative_id": "5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d",
        "creative_code": "ACV001-FILM0001-EP1-2-F1-TEAM",
        "name": "Heiress returns - wedding hook",
        "status": "approved",
        "created_at": 1790500000,
        "approved_at": 1790590000,
        "updated_at": 1790610000,
        "org": { "slug": "your-org" },
        "film": { "code": "FILM0001", "title": "The Heiress Returns", "language": "en", "genres": ["romance", "revenge"] },
        "episodes": [1, 2],
        "placement": "reels_9x16",
        "aspect": "9:16",
        "duration_ms": 21500,
        "scenes": [
          { "episode_no": 1, "start_ms": 12000, "end_ms": 19500, "duration_ms": 7500, "action": "reveal", "line": "You threw me out. Now watch me take it all back." },
          { "episode_no": 2, "start_ms": 40000, "end_ms": 54000, "duration_ms": 14000, "action": null, "line": null }
        ],
        "hook": { "action": "reveal", "line": "You threw me out. Now watch me take it all back." },
        "formula": { "name": "Cliffhanger opener" },
        "rights": { "ends_at": 1798675200 },
        "lineage": { "parent_creative_id": null },
        "final": { "ready": true, "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } }
      }
    ],
    "next_cursor": "eyJwIjoiZXhhbXBsZS1jdXJzb3IifQ"
  },
  "server_time": 1790679032
}

Lỗi

Status	`code`	Khi nào
401	4010	Thiếu header `Authorization: Bearer`.
401	4011	Key không tồn tại hoặc đã bị thu hồi.
403	4030	Key thiếu scope `creatives:export`.
403	4031	Quyền truy cập của tổ chức bạn đang bị tạm ngưng.
422	4220	`limit` không phải số nguyên từ 1 đến 100.
422	4221	`updated_since` không phải giây epoch.
422	4222	`cursor` không hợp lệ.
429	không có	Đã chạm rate limit. Body phẳng với `error_code` `rate_limited`, không phải envelope.
503	5030	Feed tạm thời không khả dụng. Retry với backoff.
503	5031	Wandura chưa kiểm được API key kịp thời. Key không sai: retry với backoff.

Xem Lỗi để biết cách xử lý từng trường hợp.

Liệt kê creative

Mô tả#

Tham số request#

Ví dụ request#

Response#

Bản ghi creative#

Ví dụ response#

Lỗi#