Bỏ qua menu, tới nội dung

WanduraDocsBeta

API v1

BetaDocs đang ở bản beta và còn thay đổi. Thấy chỗ sai, khó hiểu hoặc còn thiếu? Hãy cho chúng tôi biết.

Tài liệu tham chiếu API

Lấy một creative

Trên trang này

Mô tả
Tham số request
Ví dụ request
Response
Ví dụ response
Header của response
Lỗi

Trả về bản ghi dữ liệu của một creative đã duyệt thuộc tổ chức của bạn. Dùng endpoint này để lấy một creative, hoặc kiểm tra một creative bạn đã lưu có còn khả dụng không.

GET /api/delivery/v1/creatives/{id}

Scope: creatives:export

Mô tả

Trả về cùng bản ghi như Liệt kê creative, được bọc trong envelope {code, message, data, server_time}. Creative không tồn tại, thuộc tổ chức khác, hoặc không ở status approved hay pushed đều trả về cùng một 404, nên bạn không phân biệt được các trường hợp này.

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`.
`id`	path	string	Có	`creative_id` của creative. Giá trị không phải UUID sẽ trả 404.
`Wandura-Version`	header	string	Không	Tuỳ chọn. Một phiên bản API theo ngày (YYYY-MM-DD) dùng cho request này thay cho bản ghim vào API key của bạn. Giá trị lạ hoặc đã ngừng trả 400 với `error_code` `unsupported_version`.

Ví dụ request

curl -s https://www.wandura.ai/api/delivery/v1/creatives/5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Response

200 OK

Trường	Kiểu	Mô tả
`code`	integer	`0`.
`message`	string	`"ok"`.
`data`	object	Bản ghi dữ liệu của một creative đã duyệt. Không bao giờ chứa URL media.
`server_time`	integer	Giờ server tính bằng giây Unix epoch.
`links`	object	URL tuyệt đối dựng sẵn của response này.

Ví dụ response

{
  "code": 0,
  "message": "ok",
  "data": {
    "schema_version": 1,
    "creative_id": "5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d",
    "creative_code": "ACV001-FILM0001-EP1-2-F1-TEAM",
    "name": "Heiress returns - wedding hook",
    "status": "pushed",
    "created_at": 1790500000,
    "approved_at": 1790590000,
    "updated_at": 1790640000,
    "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" } }
  },
  "server_time": 1790679032
}

Header của response

Header	Response	Mô tả
`Wandura-API-Status`	mọi response	Trạng thái API. Hiện là `beta`, ở mọi response, thành công hay lỗi.
`Wandura-Version`	mọi response	Phiên bản API theo ngày (YYYY-MM-DD) mà response này dùng: bản ghim vào API key của bạn, hoặc bản bạn gửi trong header request `Wandura-Version`. Key tạo trước khi có phiên bản ngày dùng `2026-10-02`.
`Wandura-Request-Id`	mọi response	Mã định danh mờ của request này (`req_` và 26 ký tự). Mọi response đều có, kể cả lỗi, và body lỗi lặp lại nó ở `request_id`. Hãy ghi log nó, và gửi kèm khi liên hệ Wandura về một request: nó tìm đúng request đó trong log của chúng tôi. Đừng phân tích chuỗi này.
`Deprecation`	200	Chỉ có khi endpoint này, hoặc phiên bản ngày đang phục vụ response, đã bị ngừng hỗ trợ (RFC 9745): `@<giây unix>` của ngày ngừng. Hãy ghi nó vào hệ giám sát.
`Sunset`	200	Chỉ có khi endpoint hay phiên bản ngày đã bị ngừng có ngày thôi chạy (RFC 8594), dạng ngày HTTP.
`Link`	200	Có kèm `Deprecation`: `<https://docs.wandura.ai/…>; rel="deprecation"` (và `rel="sunset"`) trỏ tới trang giải thích dùng gì thay thế.
`Cache-Control`	mọi response	Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung.
`Retry-After`	429	Số giây cần chờ trước khi thử lại. Có ở response 429 và các response 503 nên thử lại.
`X-RateLimit-Limit`	429	Số request (với playback là số vé) được phép trong một cửa sổ cho nhóm endpoint này và tổ chức của bạn.
`X-RateLimit-Window`	429	Độ dài cửa sổ tính bằng giây.

Lỗi

Status	`code`	Khi nào
400	không có	Header `Wandura-Version`, hoặc bản ghim của key, là bản lạ hay đã ngừng. Body có thêm `supported_versions` và `latest_version` (và `upgrade_to` khi bản ghim đã ngừng).
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.
404	4040	Không có creative đã duyệt nào với ID này cho tổ chức của bạn, hoặc ID không phải UUID.
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.

Cập nhật 05/10/2026 · Lịch sử thay đổi (6)