Wan Video API

Trang này mô tả cách gọi các model video Wan của Alibaba, wan3.0-video và wan3.0-video-prime. Giống các model video khác, chúng được tạo bằng POST /v1/videos và truy vấn bằng GET /v1/videos/{id}; xác thực, tải lên tư liệu, trạng thái truy vấn định kỳ, tải kết quả và xử lý lỗi xem Quy chuẩn gọi Video API đầy đủ. Trang này chỉ trình bày các trường và quy tắc riêng của Wan. Wan cũng có thể gửi bằng POST /v1/responses; xem mục “Gọi qua Responses API” bên dưới.

Cập nhật ngày 2026-10-12. Các model cũ wan3.0-video-480p, wan3.0-video-720p, wan3.0-video-1080p đã được gộp thành wan3.0-video, độ phân giải chọn bằng resolution. Khung hình đầu, khung hình cuối và tư liệu tham chiếu nên đặt trong mảng media ở cấp gốc (first_frame, last_frame, reference_image...). Cũng hỗ trợ metadata.firstFrame, metadata.lastFrame, metadata.referenceImages, metadata.referenceVideos, metadata.referenceAudios (kể cả dạng gạch dưới như metadata.first_frame) và firstFrame / first_frame, lastFrame / last_frame ở cấp gốc; tất cả được chuyển thành media, nhưng không gửi cùng lúc với media. Trường tư liệu không đọc được sẽ trả lỗi 400. Wan chỉ hỗ trợ truy vấn định kỳ, không đặt callback_url.

Model

Model	Độ phân giải	Thời lượng	Tỷ lệ khung hình	Giới hạn tư liệu tham chiếu
`wan3.0-video`	480P / 720P / 1080P, mặc định 1080P	`-1` hoặc 2–30 giây, mặc định 5 giây	`adaptive` `16:9` `9:16` `1:1` `4:3` `3:4` `21:9`, mặc định `adaptive`	10 ảnh / 5 video / 5 âm thanh
`wan3.0-video-prime`	Như trên	Như trên	Như trên	Như trên

Hai model có cùng khả năng: quy tắc về độ phân giải, thời lượng, tỷ lệ khung hình, khung hình đầu/cuối và tham chiếu đa phương thức đều giống nhau, tham số yêu cầu dùng chung, muốn chuyển đổi chỉ cần đổi model. Khác biệt nằm ở tốc độ tạo: wan3.0-video-prime là phiên bản tốc độ cao, toàn bộ quá trình tạo nhanh hơn rõ rệt, phù hợp khi cần có video thành phẩm sớm nhất; wan3.0-video là phiên bản tiêu chuẩn, đủ dùng khi không gấp về thời gian.

Quy tắc chung

Độ phân giải: resolution ở cấp gốc nhận 480p, 720p hoặc 1080p (không phân biệt hoa thường); mặc định 1080P. Cũng có thể dùng size để chỉ định kích thước pixel (ví dụ 1280x720, 1920x1080), đồng thời quyết định độ phân giải và tỷ lệ khung hình; size cũng có thể ghi tỷ lệ khung hình (ví dụ "size": "9:16"), nếu không khớp với ratio/aspect_ratio sẽ trả về 400.
Thời lượng: số giây nguyên trong duration (hoặc seconds); -1 để model tự xác định thời lượng một cách thông minh.
Tỷ lệ khung hình: dùng ratio (hoặc aspect_ratio tương đương); nếu hai giá trị không khớp sẽ trả về 400. adaptive thích ứng theo tư liệu đầu vào.
Prompt: có thể bỏ trống prompt khi có khung hình đầu hoặc tư liệu tham chiếu, nhưng nên mô tả chuyển động và máy quay; nếu không có cả hai sẽ trả về 400.
Trường tùy chọn:
- negative_prompt: prompt phủ định;
- prompt_extend: tự động viết lại prompt, boolean, mặc định true;
- watermark: có thêm watermark hay không, boolean;
- seed: số nguyên từ -1 đến 2147483647.

{
  "model": "wan3.0-video",
  "prompt": "Siêu xe màu bạc trong thành phố đêm mưa, máy quay góc thấp bám theo, phản chiếu ánh đèn neon, chất điện ảnh",
  "duration": 10,
  "resolution": "1080p",
  "ratio": "16:9"
}

Khung hình đầu và khung hình đầu/cuối

Khung hình đầu và khung hình cuối hãy đặt trong mảng media: first_frame là khung hình đầu, last_frame là khung hình cuối (có khung hình cuối thì bắt buộc có khung hình đầu). Ảnh tham chiếu cũng gửi qua media (reference_image), xem mục tiếp theo.

{
  "model": "wan3.0-video-prime",
  "prompt": "Chuyển mượt từ quảng trường vắng lúc sáng sớm sang cùng bố cục vào ban đêm khi đèn bật sáng",
  "duration": 8,
  "resolution": "720p",
  "media": [
    { "type": "first_frame", "url": "https://cdn.example.com/start.jpg" },
    { "type": "last_frame", "url": "https://cdn.example.com/end.jpg" }
  ]
}

Cách gửi các trường tư liệu

Nên dùng media. images / image ở cấp gốc (ảnh 1 là khung hình đầu, ảnh 2 là khung hình cuối), metadata.firstFrame (hoặc metadata.first_frame) và firstFrame / first_frame ở cấp gốc cũng dùng được. Trường tư liệu không đọc được (ví dụ metadata.image, metadata.images) trả lỗi 400 kèm gợi ý dùng media; cùng một tư liệu gửi bằng nhiều tên với URL khác nhau cũng trả lỗi 400.

Tham chiếu đa phương thức: mảng `media`

Ảnh, video và âm thanh tham chiếu đều đặt trong mảng media ở cấp gốc; mỗi phần tử có dạng { "type": "...", "url": "..." }:

`type`	Mục đích	Giới hạn
`first_frame`	Khung hình đầu	1
`last_frame`	Khung hình cuối, cần đồng thời có `first_frame`	1
`reference_image`	Ảnh tham chiếu	10
`reference_video`	Video tham chiếu	5
`reference_audio`	Âm thanh tham chiếu	5

Khung hình đầu và cuối không thể dùng chung với ảnh, video hoặc âm thanh tham chiếu.
Khi đã gửi media, chỉ media được đọc; nếu images, image hoặc các trường tương tự chứa tư liệu không có trong media sẽ trả về 400. Khung hình đầu và cuối cũng hãy đặt trong media.
URL tư liệu phải truy cập được ẩn danh, xem Yêu cầu đối với URL tư liệu. Tệp cục bộ hãy lấy URL trước theo Tải lên tư liệu cục bộ. Wan không hỗ trợ tải tệp lên bằng multipart/form-data.

{
  "model": "wan3.0-video",
  "prompt": "Người trong ảnh nhảy theo nhịp của âm thanh tham chiếu, động tác theo phong cách của video tham chiếu",
  "duration": 10,
  "resolution": "720p",
  "ratio": "9:16",
  "media": [
    { "type": "reference_image", "url": "https://cdn.example.com/dancer.jpg" },
    { "type": "reference_video", "url": "https://cdn.example.com/dance-motion.mp4" },
    { "type": "reference_audio", "url": "https://cdn.example.com/music.mp3" }
  ]
}

Gọi qua Responses API

Hai model này cũng có thể gửi bằng POST /v1/responses, phù hợp với client hoặc quy trình chỉ gọi được Responses API. Nó tạo cùng loại tác vụ video như /v1/videos, quy tắc tham số và cách tính phí giống hệt.

Prompt đặt trong input: có thể là chuỗi hoặc mảng tin nhắn. Phần input_text trong tin nhắn là prompt, phần input_image là ảnh tư liệu, theo cùng quy tắc với images ở cấp cao nhất (ảnh 1 là khung hình đầu, ảnh 2 là khung hình cuối).
Các tham số khác (resolution, duration, ratio, media, negative_prompt, ...) vẫn đặt ở cấp cao nhất của yêu cầu, cách viết như trên.
Có ba cách nhận kết quả:

Cách	Cách viết	Ghi chú
Chờ đồng bộ	Không truyền `stream` và `background`	Kết nối được giữ đến khi video tạo xong rồi trả kết quả trực tiếp, chờ tối đa khoảng 10 phút. Nếu quá thời gian sẽ trả về `"status": "incomplete"`; tác vụ vẫn tiếp tục, hãy truy vấn bằng `id` được trả về
Chạy nền	`"background": true`	Trả về `id` ngay (trạng thái `queued` hoặc `in_progress`), sau đó truy vấn định kỳ `GET /v1/responses/{id}` cho đến khi `status` là `completed` hoặc `failed`
Streaming	`"stream": true`	Gửi sự kiện SSE `response.created`, `response.in_progress` (kèm tiến độ); khi xong gửi `response.output_text.done` và `response.completed`, khi lỗi gửi `response.failed`

{
  "model": "wan3.0-video-prime",
  "input": "Chiếc xe thể thao màu bạc giữa thành phố mưa đêm, máy quay góc thấp bám theo, phản chiếu đèn neon, phong cách điện ảnh",
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "background": true
}

Khi video tạo xong, địa chỉ video nằm trong output[0].content[0].text dưới dạng <video controls src="địa chỉ video"></video>; lấy giá trị src để tải xuống:

{
  "id": "resp_BVQwZLWyXB2dEU99F7nrER7XNJdVh8RS",
  "object": "response",
  "model": "wan3.0-video-prime",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        { "type": "output_text", "text": "<video controls src=\"https://...\"></video>" }
      ]
    }
  ],
  "metadata": {
    "task_id": "task_BVQwZLWyXB2dEU99F7nrER7XNJdVh8RS",
    "task_status": "completed"
  }
}

metadata.task_id là mã tác vụ video tương ứng; bạn cũng có thể truy vấn cùng tác vụ bằng GET /v1/videos/{task_id}.

API chat không tạo được video

Chỉ Wan hỗ trợ /v1/responses. /v1/chat/completions, /v1/messages và các API tạo ảnh không gọi được model video và sẽ trả về 400 video_model_wrong_endpoint.

Thanh toán

wan3.0-video và wan3.0-video-prime là bản chính thức, URL kết quả là URL chính thức. Thanh toán theo quy tắc chính thức:

Thời lượng tính phí = thời lượng video đầu vào + thời lượng video đầu ra

Thời lượng đầu vào: số giây thực tế của video tham chiếu; bằng 0 nếu không có video tham chiếu.
Thời lượng đầu ra: số giây video tạo thành công.
Đơn giá theo giây lấy theo độ phân giải đầu ra (480P / 720P / 1080P). Đầu vào và đầu ra dùng cùng một mức giá.
Ảnh tham chiếu, âm thanh tham chiếu, tệp và trang web không cộng vào thời lượng tính phí.
Có video tham chiếu, hoặc duration là -1, hệ thống tạm trừ 30 giây khi tạo; sau khi hoàn tất sẽ quyết toán theo số giây đầu vào + đầu ra mà nền tảng model trả về và hoàn phần dư.

Đơn giá mỗi giây lấy theo trang mô hình hiện tại. Không ước tính tác vụ có video tham chiếu chỉ theo giây đầu ra.