Lịch sử thay đổi
Mọi lần sửa trang này, mới nhất ở trên. Mở từng mục để xem đã đổi gì.
- 19/10/2026 · +4 −4 dòng
Xem thay đổi
⋯ ## 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. 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). + 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 đã ký. 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 {#request-parameters} ⋯ ### Bản ghi creative {#the-creative-record} - [Lấy một creative](creatives-get.md) trả về cùng bản ghi này. `final.file_url` là URL API bền để tải video cuối: gọi bằng API key của bạn; nó chuyển hướng tới link tải dùng được 15 phút ([Tải file cuối của một creative](creatives-file.md)). Trường này là `null` cho tới khi `final.ready` là `true`. + [Lấy một creative](creatives-get.md) trả về cùng bản ghi này. `final.file_url` là link chia sẻ công khai của creative: không cần API key, bền, thu hồi được trên portal. Mỗi lần mở chuyển hướng tới link tải mới dùng được 15 phút, nên đưa thẳng cho video upload của Meta được. Trường này là `null` cho tới khi `final.ready` là `true`, và `null` khi admin của tổ chức bạn đã thu hồi link. Xem [Tải file cuối](../concepts/creatives.md#downloading-the-final-file); muốn tải bằng API key thì dùng [Tải file cuối của một creative](creatives-file.md). | Trường | Kiểu | Mô tả | ⋯ | `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.file_url` | string hoặc null | URL API bền để tải video cuối (`GET /api/delivery/v1/creatives/{id}/file`); `null` cho tới khi `ready` là `true`. Gọi bằng API key của bạn; nó chuyển hướng tới link tải dùng được 15 phút. File là bản cuối sạch, có brand mark của công ty bạn nếu tổ chức bạn có. Đây là URL API, không phải URL media: bạn lưu lại được. | + | `final.file_url` | string hoặc null | Link tải công khai, bền (không cần API key) — thu hồi được trên portal; mỗi lần mở chuyển hướng tới một link tải mới dùng được 15 phút. Đưa thẳng cho video upload của Meta được. Dạng `https://www.wandura.ai/api/c/{token}.mp4`; mỗi lần mở đều kiểm lại creative còn được duyệt và quyền export phim của bạn còn hiệu lực (không thì `410`). File là bản cuối sạch, có brand mark của công ty bạn nếu tổ chức bạn có. `null` cho tới khi `ready` là `true`, và `null` khi admin của tổ chức bạn đã thu hồi link: hỏi admin, hoặc tạo share link mới trên portal. Ai có link đều tải được file, nên giữ nó như mật khẩu. Muốn tải bằng API key thì gọi `GET /api/delivery/v1/creatives/{id}/file`. | | `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ó. | ⋯ "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" } } ⋯
- 19/10/2026 · +7 −2 dòng
Xem thay đổi
⋯ ### Bản ghi creative {#the-creative-record} - [Lấy một creative](creatives-get.md) trả về cùng bản ghi này. + [Lấy một creative](creatives-get.md) trả về cùng bản ghi này. `final.file_url` là URL API bền để tải video cuối: gọi bằng API key của bạn; nó chuyển hướng tới link tải dùng được 15 phút ([Tải file cuối của một creative](creatives-file.md)). Trường này là `null` cho tới khi `final.ready` là `true`. | Trường | Kiểu | Mô tả | ⋯ | `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.file_url` | string hoặc null | URL API bền để tải video cuối (`GET /api/delivery/v1/creatives/{id}/file`); `null` cho tới khi `ready` là `true`. Gọi bằng API key của bạn; nó chuyển hướng tới link tải dùng được 15 phút. File là bản cuối sạch, có brand mark của công ty bạn nếu tổ chức bạn có. Đây là URL API, không phải URL media: bạn lưu lại đượ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ó. | ⋯ "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" } + } } ], ⋯
- 19/10/2026 · +4 −0 dòng
Xem thay đổi
⋯ | `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. | + | `created_by` | object hoặc null | Người đã tạo creative. `null` khi không xác định được người tạo, ví dụ creative do hệ thống tạo hoặc do một user đã bị xoá tài khoản. | + | `created_by.email` | string | Email của người tạo. | + | `created_by.name` | string hoặc null | Tên hiển thị của người tạo. `null` khi người tạo chưa đặt tên. | | `film` | object hoặc null | Phim mà creative được cắt từ đó. | | `film.code` | string hoặc null | Mã phim. | ⋯ "updated_at": 1790610000, "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], ⋯
- 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