Lấy metadata một playlist

Dành cho đối tác video. Trả về một playlist cho CMS của bạn: Category, nhóm, tên, mô tả, ảnh, và các clip theo thứ tự kèm tên, mô tả, thời lượng, nhóm cơ, dụng cụ, độ khó, calo, poster và mã đơn sản xuất. Khi tổ chức của bạn được cấp playlist này, nó cho biết thêm bản chép của bạn nằm ở đâu trong media space của bạn. Gọi khi Liệt kê playlist hiện một content_version bạn chưa lưu.

GET /api/delivery/v1/playlists/{code}

Scope: metadata:read

Mô tả

Đọc được mọi playlist trong kho, dù được cấp hay chưa. Khi granted là true, media cho biết media space của bạn và playlist trong đó, mỗi clip đã chép kèm video ID (vid) và format (hls hoặc mp4). Khi granted là false, media là null và mọi clip có ready: false, không có video ID. Không có link phát: app của bạn phát bản chép thẳng từ media space của chính bạn.

Playlist không tồn tại và playlist không còn trong kho (đã withdrawn, hoặc Category của nó đã withdrawn) trả cùng một 404. Key của tổ chức lấy phim nhận 403 4032; hãy dùng Lấy metadata một bộ phim.

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 dùng định dạng phẳng. Endpoint này dùng chung bộ đếm rate limit với catalog.

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 `metadata:read`.
`code`	path	string	Có	Mã playlist, ví dụ `wall-pilates-01` (`code` trong danh sách).
`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/playlists/wall-pilates-01 \
  -H "Authorization: Bearer $WANDURA_API_KEY"

Response

200 OK. Trường mới có thể được thêm bất cứ lúc nào: bỏ qua trường bạn không biết.

Trường	Kiểu	Mô tả
`code`	integer	`0`.
`message`	string	`"ok"`.
`data`	object
`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 chính tài nguyên này (link API, không phải file media).

Các trường của một playlist (`data`)

Trường	Kiểu	Mô tả
`code`	string	Mã playlist.
`status`	string	Luôn là `active` (playlist không có trong kho trả 404).
`title`	string	Tên playlist.
`description`	string hoặc null	Mô tả playlist, hoặc `null`.
`category`	object	Category của playlist (ví dụ Fitness).
`category.slug`	string	Mã ổn định của Category, ví dụ `fitness`. Cũng là bộ lọc `category` của danh sách.
`category.name`	string	Tên hiển thị.
`group`	object hoặc null	Nhãn lọc của playlist trong Category (ví dụ Pilates hoặc Gym), hoặc `null`. Không phải đơn vị cấp quyền.
`group.code`	string	Mã ổn định.
`group.title`	string	Tên hiển thị.
`updated_at`	integer	Lần đổi gần nhất tính bằng giây Unix epoch.
`content_version`	string	Mã băm của toàn bộ response này. Lưu lại; danh sách trả cùng giá trị thì không có gì phải tải.
`metadata_version`	string hoặc null	Mã băm của riêng metadata playlist (giống nhau với mọi tổ chức).
`granted`	boolean	`true` khi tổ chức của bạn được cấp playlist này.
`media`	object hoặc null	Bản chép của bạn nằm ở đâu, hoặc `null` khi playlist chưa được cấp. Việc phát diễn ra giữa app và media space của bạn; API này không bao giờ trả link phát.
`media.space`	string hoặc null	Media space của bạn cho Category này, hoặc `null` khi chưa dựng.
`media.playlist_id`	string hoặc null	ID playlist trong `space` (đặt tên theo `code`), hoặc `null` cho tới khi nó tồn tại.
`media.playlist_name`	string hoặc null	Tên playlist đó, hoặc `null`.
`media.playlists`	array	Mọi playlist chứa các clip theo thứ tự (mỗi cái tối đa 100 video, nên playlist dài hơn nối tiếp ở `<code>-2`…).
`images`	array	Ảnh của playlist. Hiện có một `cover` (poster của clip đầu tiên); có thể có thêm loại. Rỗng khi không có.
`images[].kind`	string	`cover`. Có thể có loại mới.
`images[].source`	string	`media_space` hoặc `wandura_cdn`. Có thể có giá trị mới.
`images[].url`	string hoặc null	URL ảnh khi `source` là `wandura_cdn`, ngược lại `null`. Tải về và tự lưu bản của bạn.
`images[].expires_at`	integer hoặc null	Lúc `url` hết hiệu lực, tính bằng giây Unix epoch, hoặc `null`.
`images[].space`	string hoặc null	Media space của bạn đang chứa ảnh, hoặc `null`.
`images[].uri`	string hoặc null	URI của ảnh trong `space`, hoặc `null`.
`clips`	array	Các clip theo thứ tự playlist.
`clips[].position`	integer	Vị trí trong playlist. Các clip trả về theo thứ tự này.
`clips[].id`	string (UUID)	Clip ID. Không bao giờ đổi; đồng bộ theo trường này. Một clip có thể nằm trong nhiều playlist.
`clips[].title`	string	Tên clip.
`clips[].description`	string hoặc null	Mô tả ngắn, hoặc `null`.
`clips[].duration_ms`	integer hoặc null	Thời lượng tính bằng mili giây.
`clips[].muscle_groups`	mảng string	Nhóm cơ được tập. Có thể rỗng.
`clips[].equipment`	mảng string	Dụng cụ cần có. Có thể rỗng.
`clips[].difficulty`	string hoặc null	`beginner`, `intermediate` hoặc `advanced`, hoặc `null`.
`clips[].kcal_est`	integer hoặc null	Lượng calo ước tính tiêu hao.
`clips[].order_code`	string hoặc null	Mã đơn sản xuất (ví dụ `ABS_01_E01`), khớp từng ký tự với file đặt hàng của bạn, hoặc `null`.
`clips[].poster`	object hoặc null	Một ảnh, hoặc `null` khi không có. `source` cho biết lấy ở đâu. `media_space`: ảnh đã nằm trong media space của bạn (`space`) tại `uri` (với clip đó cũng là poster gắn trên `vid` của nó); tải qua space của bạn như cách bạn tải video. `wandura_cdn`: link dùng được tới `expires_at`; tải file về và tự lưu bản của bạn, đừng lưu link. Có thể có nguồn mới: bỏ qua giá trị bạn không biết.
`clips[].poster.source`	string	`media_space` (trong media space của bạn) hoặc `wandura_cdn` (link Wandura để tải về). Có thể có giá trị mới.
`clips[].poster.url`	string hoặc null	URL ảnh khi `source` là `wandura_cdn`, ngược lại `null`.
`clips[].poster.expires_at`	integer hoặc null	Lúc `url` hết hiệu lực, tính bằng giây Unix epoch, hoặc `null`.
`clips[].poster.space`	string hoặc null	Media space của bạn đang chứa ảnh khi `source` là `media_space`, ngược lại `null`.
`clips[].poster.uri`	string hoặc null	URI của ảnh trong `space` khi `source` là `media_space`, ngược lại `null`.
`clips[].ready`	boolean	`true` khi clip đã chép xong và phát được trong media space của bạn (`media.space`).
`clips[].vid`	string hoặc null	Video ID của clip trong media space của bạn, hoặc `null` khi chưa chép (hoặc playlist chưa được cấp).
`clips[].format`	string hoặc null	Dạng đóng gói của bản chép: `hls` (clip từ 30 giây) hoặc `mp4` (clip ngắn hơn). `null` khi chưa chép.
`clips[].playlist_id`	string hoặc null	ID playlist trong media space của bạn đang chứa clip này, hoặc `null`.
`clips[].playlist_name`	string hoặc null	Tên playlist đó, hoặc `null`.

Ảnh

Mỗi ảnh (ảnh cover của playlist trong images[], và poster của từng clip) ghi trong source chỗ lấy nó. media_space: ảnh đã nằm trong media space của bạn (space, uri); tải qua space của bạn như cách tải video. wandura_cdn: url là link dùng được 1 giờ (tới expires_at); tải file về và tự lưu bản của bạn, không bao giờ lưu link. Ảnh không có thì là null.

Ví dụ response

{
  "code": 0,
  "message": "ok",
  "data": {
    "code": "wall-pilates-01",
    "status": "active",
    "title": "Wall Pilates",
    "description": "Ten low-impact moves using a wall for support.",
    "category": { "slug": "fitness", "name": "Fitness" },
    "group": { "code": "pilates", "title": "Pilates" },
    "updated_at": 1790390000,
    "content_version": "5d41402abc4b2a76b9719d911017c592",
    "metadata_version": "0cc175b9c0f1b6a831c399e269772661",
    "granted": true,
    "media": {
      "space": "your-fitness-space",
      "playlist_id": "9f8e7d6c5b4a3921",
      "playlist_name": "wall-pilates-01",
      "playlists": [{ "id": "9f8e7d6c5b4a3921", "name": "wall-pilates-01" }]
    },
    "images": [{ "kind": "cover", "source": "media_space", "url": null, "expires_at": null, "space": "your-fitness-space", "uri": "your-fitness-space/fit-3f2a1b4c.jpg" }],
    "clips": [
      {
        "position": 1,
        "id": "3f2a1b4c-5d6e-4f70-8a9b-0c1d2e3f4a5b",
        "title": "Wall Squat",
        "description": "Slide down the wall and hold.",
        "duration_ms": 45000,
        "muscle_groups": ["quads", "glutes"],
        "equipment": ["wall"],
        "difficulty": "intermediate",
        "kcal_est": 9,
        "order_code": "ABS_01_E01",
        "poster": { "source": "media_space", "url": null, "expires_at": null, "space": "your-fitness-space", "uri": "your-fitness-space/fit-3f2a1b4c.jpg" },
        "ready": true,
        "vid": "v0a1b2c3d4e5f6",
        "format": "hls",
        "playlist_id": "9f8e7d6c5b4a3921",
        "playlist_name": "wall-pilates-01"
      }
    ]
  },
  "server_time": 1790400000
}

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`	200	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`	200	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.
`Cache-Control`	200	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.

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.
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 `metadata:read`.
403	4031	Quyền truy cập của tổ chức bạn đang bị tạm ngưng.
403	4032	Metadata playlist dành cho đối tác video; tổ chức của bạn lấy phim (dùng các endpoint series).
404	4040	Không có playlist này, hoặc nó không có trong kho (cố ý trả cùng một câu).
429	không có	Đã chạm rate limit.
503	5030	Playlist tạm thời không khả dụng.
503	5031	Wandura chưa kiểm được API key kịp thời.

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

Lấy metadata một playlist

Mô tả#

Tham số request#

Ví dụ request#

Response#

Các trường của một playlist (data)#

Ảnh#

Ví dụ response#

Header của response#

Lỗi#