Bản lưu ngày / Snapshot of 2026-10-05 · Xem bản mới nhất / See the latest version
WanduraDocsBeta
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.
Bạn đang đọc một bản tài liệu cũ: v1 · Sang bản mới nhất (v2)
Tài liệu tham chiếu API

Lấy metadata một bộ phim

Markdown
Trên trang này

Trả về mọi thứ Wandura biết về một bộ cho CMS của bạn: tên và tóm tắt theo ngôn ngữ, thẻ thể loại và chủ đề có mã, độ tuổi, diễn viên hoặc nhân vật chính, ảnh kèm kích thước, ngôn ngữ âm thanh, cờ đã ra hết tập, và các tập đã phát hành kèm video ID và file phụ đề. Gọi endpoint này khi Liệt kê bộ phim trả một content_version bạn chưa lưu.

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

Scope: metadata:read

Mô tả

Giá trị thiếu là null hoặc rỗng: không bao giờ chặn giấy phép. Bộ không tồn tại và bộ bạn không được stream trả về cùng một 404, nên bạn không phân biệt được hai trường hợp này. 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.

CMS của bạn được sửa đè bất kỳ trường nào. Wandura không bao giờ ghi đè bản sửa của bạn.

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ã bộ, ví dụ WD000016 (code trong catalog hoặc 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/series/WD000016 \
  -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 bộ (data)

Trường Kiểu Mô tả
code string Mã bộ, ví dụ WD000016.
status string Luôn là active (bộ bạn không được stream trả 404).
updated_at integer Lần đổi gần nhất tính bằng giây Unix epoch.
content_version string hoặc null 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.
language string hoặc null Ngôn ngữ âm thanh, BCP-47 (giống default_lang).
default_lang string hoặc null Ngôn ngữ âm thanh, BCP-47.
title_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
synopsis_short_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
synopsis_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
genres mảng string Nhãn thể loại chữ tự do (cũ). Nên dùng tags.
poster object hoặc null Ảnh bìa 9:16 dạng {url}, hoặc null. Cùng ảnh có trong images kèm kích thước.
content_rating string hoặc null Độ tuổi, hoặc null khi chưa chấm.
is_completed boolean hoặc null true khi mọi tập dự kiến đã ra.
release_date string hoặc null Ngày phát hành gốc, hoặc null.
planned_episodes integer hoặc null Tổng số tập dự kiến, hoặc null.
tags array
tags[].slug string Mã ổn định của thẻ, ví dụ romance hoặc enemies-to-lovers. Ánh xạ sang danh sách thẻ của bạn theo giá trị này, không theo name.
tags[].name string Tên hiển thị tiếng Anh.
tags[].name_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
tags[].type string genre, theme hoặc system. Có thể có loại mới.
tags[].is_main boolean true với thể loại chính của phim (tối đa một).
people array
people[].name string Tên diễn viên hoặc nhân vật.
people[].role string lead hoặc support.
people[].description string hoặc null Mô tả một câu, hoặc null.
people[].avatar_url string hoặc null URL ảnh https tuyệt đối, hoặc null.
images array
images[].kind string Ảnh dùng cho việc gì: poster_3_4 (poster thẻ 3:4), cover_9_16 (ảnh bìa toàn màn hình 9:16, cùng ảnh với poster_url), hero_16_9 (banner 16:9) hoặc title_treatment (tên phim dạng ảnh). Có thể có loại mới: bỏ qua loại bạn không biết.
images[].lang string hoặc null Ngôn ngữ của chữ in sẵn trong ảnh (BCP-47), hoặc null khi ảnh dùng được cho mọi ngôn ngữ. Ưu tiên phần tử khớp ngôn ngữ người dùng, không có thì lấy phần tử null.
images[].url string URL https tuyệt đối của ảnh trên host của Wandura. Tải thẳng được, không cần ký.
images[].width integer hoặc null Chiều rộng tính bằng pixel, đo từ chính file. null khi Wandura chưa ghi kích thước.
images[].height integer hoặc null Chiều cao tính bằng pixel, đo từ chính file. null khi Wandura chưa ghi kích thước.
trailer object hoặc null Video ID trailer trong media space của Wandura, hoặc null. Luôn null khi bạn có space riêng.
metadata_version string hoặc null Mã băm của riêng metadata phim (cùng giá trị như trong catalog).
metadata_updated_at integer hoặc null Lúc metadata_version đổi gần nhất (giây epoch).
media object Video nằm ở đâu: space là media space (của bạn nếu bạn có space riêng) và playlist_name là playlist chứa các tập theo thứ tự (bằng code).
episodes array Các tập đã phát hành, theo ep_number.
episodes[].ep_number integer Số tập, bắt đầu từ 1. Thứ tự playlist theo số này.
episodes[].vid string hoặc null Video ID của tập trong media space ghi ở media.space (space riêng của bạn nếu có). null khi tập chưa có trong space đó.
episodes[].ready boolean true khi tập phát được từ space đó.
episodes[].title_i18n object Chữ theo ngôn ngữ: khoá là mã BCP-47, giá trị là chữ, ví dụ {"en": "The Heiress Returns"}. Hiện Wandura điền en; có thể có thêm ngôn ngữ. Thiếu khoá nghĩa là chưa có chữ ngôn ngữ đó: lùi về en. Object rỗng khi không có chữ.
episodes[].duration_sec integer hoặc null Thời lượng tính bằng giây, chỉ để đối chiếu.
episodes[].subtitles[].lang string Mã BCP-47.
episodes[].subtitles[].url string URL file WebVTT. Tải về và tự lưu bản của bạn.
episodes[].subtitles[].updated_at integer Lần đổi file gần nhất (giây epoch).

URL ảnh và phụ đề là URL https tuyệt đối trên host của Wandura. Tải file phụ đề về và tự lưu bản của bạn.

Ví dụ response

{
  "code": 0,
  "message": "ok",
  "data": {
    "code": "WD000016",
    "status": "active",
    "updated_at": 1790390000,
    "content_version": "c3f1a9e07b2d4c5e8f9a0b1c2d3e4f50",
    "language": "en",
    "default_lang": "en",
    "title_i18n": { "en": "The Hidden Alpha Bride" },
    "synopsis_short_i18n": { "en": "Rejected by her mate, a runaway omega returns as the bride of his rival." },
    "synopsis_i18n": { "en": "Rejected by her mate on the night of the bond, Luna runs. Three years later she returns as the bride of his rival." },
    "genres": ["Werewolf", "Romance"],
    "poster": { "url": "https://static.example.com/wd000016/cover.jpg" },
    "content_rating": "13+",
    "is_completed": true,
    "release_date": null,
    "planned_episodes": 60,
    "tags": [
      { "slug": "werewolf", "name": "Werewolf", "name_i18n": { "en": "Werewolf" }, "type": "genre", "is_main": true },
      { "slug": "fated-mates", "name": "Fated Mates", "name_i18n": { "en": "Fated Mates" }, "type": "theme", "is_main": false }
    ],
    "people": [{ "name": "Luna", "role": "lead", "description": "A rejected omega who returns to claim her place.", "avatar_url": null }],
    "images": [
      { "kind": "poster_3_4", "lang": null, "url": "https://static.example.com/wd000016/poster-3x4.jpg", "width": 1080, "height": 1440 },
      { "kind": "cover_9_16", "lang": null, "url": "https://static.example.com/wd000016/cover.jpg", "width": 1080, "height": 1920 }
    ],
    "trailer": null,
    "metadata_version": "9a0b1c2d3e4f5061728394a5b6c7d8e9",
    "metadata_updated_at": 1790380000,
    "media": { "space": "your-space", "playlist_name": "WD000016" },
    "episodes": [
      {
        "ep_number": 1,
        "vid": "v0d2f8c1a9e4b7",
        "ready": true,
        "title_i18n": { "en": "The Night of the Bond" },
        "duration_sec": 137,
        "subtitles": [{ "lang": "en", "url": "https://static.example.com/wd000016/1.en.vtt", "updated_at": 1790380000 }]
      }
    ]
  },
  "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.
404 4040 Không có bộ này, hoặc tổ chức của bạn không được stream nó (cố ý trả cùng một câu).
429 không có Đã chạm rate limit.
503 5030 Bộ phim 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.

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

↑↓ 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