Lịch sử: Liệt kê creative

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

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, 422, 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. |
⋯

02/10/2026 · +7 −7 dòng

Xem thay đổi

⋯
  **Scope:** `creatives:export`
  
- ## Mô tả
+ ## Mô tả {#description}
  
- 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](../concepts/creatives.md).
+ 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. Response thành công được bọc trong envelope `{code, message, data, server_time}`; lỗi dùng cùng envelope đó nhưng không có `data`, trừ `429` và `400` `unsupported_version`, hai lỗi này dùng định dạng phẳng. Xem [Creative](../concepts/creatives.md).
  
- ## Tham số request
+ ## Tham số request {#request-parameters}
  
  | Tên | Vị trí | Kiểu | Bắt buộc | Mô tả |
⋯
  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
+ ## Ví dụ request {#request-example}
  
  ```bash
⋯
  ```
  
- ## Response
+ ## Response {#response}
  
  `200 OK`
⋯
  `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
+ ## 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 |
⋯

02/10/2026 · +10 −0 dòng

Xem thay đổ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`. |
+ | `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`. |
  
  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`.
⋯
  | `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. |
+ | `links` | object | URL tuyệt đối dựng sẵn của trang này — đi theo `links.next` thay vì tự ráp URL trang kế. |
+ | `links.self` | string | Chính request này. |
+ | `links.next` | string hoặc null | Trang sau, hoặc `null` ở trang cuối. |
  
  ### Bản ghi creative {#the-creative-record}
⋯
  | Trường | Kiểu | Mô tả |
  |---|---|---|
+ | `links` | object | URL tuyệt đối dựng sẵn tới endpoint của chính creative này (link API, không phải URL media). |
  | `schema_version` | integer | Phiên bản schema của bản ghi. Hiện là `1`. Thêm trường mới không làm đổi số này. |
  | `creative_id` | string (UUID) | ID ổn định của creative. |
⋯
  |---|---|---|
  | `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, 422, 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. |
⋯

02/10/2026 · +23 −5 dòng

Xem thay đổi

⋯
  | `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](#the-creative-record). |
+ | `data.items` | array | Các bản ghi creative trên trang này. |
  | `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. |
⋯
  | Trường | Kiểu | Mô tả |
  |---|---|---|
- | `schema_version` | integer | Phiên bản schema của bản ghi. Hiện là `1`. |
+ | `schema_version` | integer | Phiên bản schema của bản ghi. Hiện là `1`. Thêm trường mới không làm đổi số này. |
  | `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. |
⋯
  | `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. |
+ | `duration_ms` | integer | Tổng độ dài các clip phim được dùng, tính bằng mili giây. Có thể ngắn hơn video hoàn chỉnh, vì `scenes` chỉ liệt kê các clip lấy từ tập phim. |
  | `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[].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. |
+ | `formula` | object hoặc null | Formula dùng để dựng creative. |
+ | `formula.name` | string | Tên formula. |
  | `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ừ đó. |
⋯
          "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, 422, 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
  
⋯

01/10/2026 · +6 −5 dòng

Xem thay đổi

⋯
  |---|---|---|---|---|
  | `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 cập nhật sau thời điểm này. |
+ | `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ộ.
+ 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
⋯
  | `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 đó. `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. |
+ | `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. |
- | `final.target` | object | Thông số render đích: `width`, `height`, `fps`, `codec`. |
+ | `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.
⋯
  | 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.

29/09/2026 · Tạo trang