WanduraDocsBeta
API v2
v2 (mới nhất)v1Nhật ký thay đổi
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.
Lịch sử thay đổi

Lịch sử: Lấy một creative

Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.

← Lấy một creative

  1. 19/10/2026 · +3 −3 dòng
    Xem thay đổi
    ⋯
  ## Mô tả {#description}
  
- Trả về cùng bản ghi như [Liệt kê creative](creatives-list.md#the-creative-record), đượ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. Để tải video cuối, gọi `final.file_url` của bản ghi ([Tải file cuối của một creative](creatives-file.md)).
+ Trả về cùng bản ghi như [Liệt kê creative](creatives-list.md#the-creative-record), đượ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. Để tải video cuối, mở `final.file_url` của bản ghi, một link chia sẻ công khai không cần API key ([Tải file cuối](../concepts/creatives.md#downloading-the-final-file)). Khi một link bạn đã lưu trả `410`, gọi lại endpoint này: nó trả link hiện tại, hoặc `null` nếu admin đã thu hồi.
  
  ## Tham số request {#request-parameters}
⋯
  | `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. |
+ | `data` | object | Bản ghi dữ liệu của một creative đã duyệt. Không bao giờ chứa URL media đã ký; `final.file_url` là link chia sẻ công khai. |
  | `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. |
⋯
      "final": {
        "ready": true,
-       "file_url": "https://www.wandura.ai/api/delivery/v1/creatives/5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d/file",
+       "file_url": "https://www.wandura.ai/api/c/Q3vh0xAbCdEfGhIjKlMnOpQrStUvWx9f.mp4",
        "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" }
      }
⋯
  2. 19/10/2026 · +6 −2 dòng
    Xem thay đổi
    ⋯
  ## Mô tả {#description}
  
- Trả về cùng bản ghi như [Liệt kê creative](creatives-list.md#the-creative-record), đượ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.
+ Trả về cùng bản ghi như [Liệt kê creative](creatives-list.md#the-creative-record), đượ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. Để tải video cuối, gọi `final.file_url` của bản ghi ([Tải file cuối của một creative](creatives-file.md)).
  
  ## Tham số request {#request-parameters}
⋯
      "rights": { "ends_at": 1798675200 },
      "lineage": { "parent_creative_id": null },
-     "final": { "ready": true, "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } }
+     "final": {
+       "ready": true,
+       "file_url": "https://www.wandura.ai/api/delivery/v1/creatives/5e1b7c3a-2d4f-4a6b-9c8d-0e1f2a3b4c5d/file",
+       "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" }
+     }
    },
    "server_time": 1790679032
⋯
  3. 19/10/2026 · +1 −0 dòng
    Xem thay đổi
    ⋯
      "updated_at": 1790640000,
      "org": { "slug": "your-org" },
+     "created_by": { "email": "maker@example.com", "name": "Alex Tran" },
      "film": { "code": "FILM0001", "title": "The Heiress Returns", "language": "en", "genres": ["romance", "revenge"] },
      "episodes": [1, 2],
⋯
  4. 02/10/2026 · +2 −1 dòng
    Xem thay đổi
    ⋯
  | `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` | 200, 401, 403, 404, 503 | Luôn là `no-store`. Đừng lưu các response này trong cache dùng chung. |
+ | `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. |
⋯
  5. 02/10/2026 · +6 −6 dòng
    Xem thay đổi
    ⋯
  **Scope:** `creatives:export`
  
- ## Mô tả
+ ## Mô tả {#description}
  
  Trả về cùng bản ghi như [Liệt kê creative](creatives-list.md#the-creative-record), đượ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
+ ## Tham số request {#request-parameters}
  
  | Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
⋯
  | `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
+ ## Ví dụ request {#request-example}
  
  ```bash
⋯
  ```
  
- ## Response
+ ## Response {#response}
  
  `200 OK`
⋯
  | `links` | object | URL tuyệt đối dựng sẵn của response này. |
  
- ## Ví dụ response
+ ## Ví dụ response {#response-example}
  
  ```json
⋯
  | `X-RateLimit-Window` | 429 | Độ dài cửa sổ tính bằng giây. |
  
- ## Lỗi
+ ## Lỗi {#errors}
  
  | Status | `code` | Khi nào |
⋯
  6. 02/10/2026 · +7 −0 dòng
    Xem thay đổi
    ⋯
  | `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
⋯
  | `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
⋯
  |---|---|---|
  | `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`. |
+ | `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` | 200, 401, 403, 404, 503 | 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. |
⋯
  | 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. |
⋯
  7. 02/10/2026 · +20 −3 dòng
    Xem thay đổi
    ⋯
  |---|---|---|---|---|
  | `Authorization` | header | string | Có | `Bearer <API key>` của một key có scope `creatives:export`. |
- | `id` | path | string (UUID) | Có | `creative_id` của creative. Giá trị không phải UUID sẽ trả `404`. |
+ | `id` | path | string | Có | `creative_id` của creative. Giá trị không phải UUID sẽ trả 404. |
  
  ## Ví dụ request
⋯
  | `code` | integer | `0`. |
  | `message` | string | `"ok"`. |
- | `data` | object | Bản ghi creative. Các trường được liệt kê trong [Bản ghi creative](creatives-list.md#the-creative-record). |
+ | `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. |
  
⋯
      "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": 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 }
      ],
⋯
  ```
  
+ ## Header của response {#response-headers}
+ 
+ | 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. |
+ | `Cache-Control` | 200, 401, 403, 404, 503 | 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
  
⋯
  8. 01/10/2026 · +10 −8 dòng
    Xem thay đổi
    ⋯
      "org": { "slug": "your-org" },
      "film": { "code": "FILM0001", "title": "The Heiress Returns", "language": "en", "genres": ["romance", "revenge"] },
-     "episodes": [1],
-     "placement": "feed_4x5",
-     "aspect": "4:5",
-     "duration_ms": 7500,
+     "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": 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": null,
-     "rights": { "ends_at": null },
+     "formula": { "name": "Cliffhanger opener" },
+     "rights": { "ends_at": 1798675200 },
      "lineage": { "parent_creative_id": null },
-     "final": { "ready": false, "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } }
+     "final": { "ready": true, "target": { "width": 1080, "height": 1920, "fps": 30, "codec": "h264" } }
    },
    "server_time": 1790679032
⋯
  | 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](../concepts/errors.md#creatives-errors) để biết cách xử lý từng trường hợp.
  9. 29/09/2026 · Tạo trang
↑↓ chọnEnter mởEsc đóng

Gửi góp ý

Góp ý được gửi thẳng tới đội Wandura, kèm địa chỉ trang này.

0 / 4000