API Wan 3.0 Video Prime

Sử dụng wan3.0-video-prime thông qua API video bất đồng bộ của APIMaster. Tích hợp hiện tại cung cấp 480P / 720P / 1080P, 2–30 giây nguyên, và một video cho mỗi tác vụ. Tham số và đánh giá tích hợp: 2026-10-26.

Điểm cuối và xác thực

Thao tác	Phương thức và URL
Tạo	POST https://apimaster.ai/v1/videos
Truy vấn	GET https://apimaster.ai/v1/videos/{task_id}
Tải xuống	GET https://apimaster.ai/v1/videos/{task_id}/content

Sử dụng Authorization: Bearer YOUR_API_KEY trên mọi yêu cầu và Content-Type: application/json khi tạo tác vụ. Dùng khóa API APIMaster, không phải khóa Alibaba Cloud. APIMaster cung cấp header bất đồng bộ thượng nguồn; bạn không cần X-DashScope-Async.

Điểm cuối tạo tương thích /videos/generations trả về một phong bì phản hồi khác; các ví dụ bên dưới luôn sử dụng /videos.

Khả năng tuyến hiện tại

Hai tích hợp hiện đang phục vụ mô hình này: tuyến gốc Alibaba Cloud và tuyến GMI. Các trường nâng cao yêu cầu tuyến tương ứng; việc gửi một trường không chọn tuyến đó. Xác nhận tuyến mà khóa API của bạn có thể truy cập trước khi sử dụng các ví dụ dành riêng cho tuyến.

Khả năng	Alibaba Cloud gốc	GMI
Văn bản-thành-video, khung đầu tiên, khung đầu/cuối, ảnh tham chiếu	Đã tích hợp	Đã tích hợp, với các trường phương tiện khác nhau
Âm thanh tham chiếu	metadata.input.media	audio_url
Tài liệu / trang web công khai	Các trường phương tiện gốc được chuyển tiếp; không được kiểm tra bởi kiểm tra tạo hoàn thành	Không được hỗ trợ
Video tham chiếu, chỉnh sửa, mở rộng	Bị chặn trước khi gửi	Không được hỗ trợ
Thời lượng tự động -1	Bị chặn	Bị chặn
Tỷ lệ khung hình 21:9	Được chấp nhận	Bị từ chối
Công tắc âm thanh rõ ràng	generate_audio / audio	Không được hỗ trợ; bỏ qua các trường này
Vô hiệu hóa viết lại prompt / seed cố định 0	Tuần tự hóa hiện tại không giữ prompt_extend: false hoặc seed: 0; không dựa vào chúng	false và 0 rõ ràng được giữ nguyên

Một video im lặng 720P 5 giây trên tuyến gốc đã hoàn thành, tải xuống và giải mã thành công trong kiểm tra chấp nhận ngày 2026-10-24. Các tổ hợp phương tiện khác được mô tả từ adapter và hợp đồng chính thức, thay vì được trình bày như các tổ hợp đã kiểm tra tạo. Tình trạng sẵn có và giá của tuyến có thể thay đổi; xem thẻ mô hình.

Tham số yêu cầu chung đầy đủ

Gửi các trường này ở cấp cao nhất. Để có tính tương thích rộng nhất, hãy sử dụng duration, resolution và aspect_ratio rõ ràng, một prompt không rỗng tối đa 5.000 ký tự, và bỏ qua các tùy chọn dành riêng cho tuyến.

Trường	Kiểu	Bắt buộc / mặc định	Hành vi APIMaster
model	string	Bắt buộc	Chính xác wan3.0-video-prime
prompt	string	Bắt buộc trên cả hai tuyến	Không rỗng, kể cả tạo ảnh. GMI xác thực 1–5.000 ký tự; adapter gốc yêu cầu văn bản không rỗng. Giới hạn gốc chính thức là 20.000; tránh dựa vào giới hạn cao hơn đó trên các tuyến
duration	integer	5	2–30 giây; không -1, phân số hoặc thời lượng tự động
seconds	string	Tùy chọn	Bí danh chuỗi, ví dụ "5"; phải khớp với duration khi cả hai được cung cấp
resolution	string	720P	480P, 720P, 1080P; các giá trị chữ thường ở cấp cao nhất được chuẩn hóa. Mặc định APIMaster này khác với mặc định gốc chính thức
aspect_ratio	string	16:9	Các giá trị phổ biến: adaptive, 16:9, 9:16, 1:1, 4:3, 3:4. 21:9 chỉ trên tuyến gốc
ratio	string	Tùy chọn	Bí danh của aspect_ratio; chỉ dùng một trường và không gửi các giá trị xung đột
size	string	Tùy chọn	Bí danh kích thước như 1280x720; áp dụng xác thực dành riêng cho tuyến. Ưu tiên resolution và aspect_ratio. GMI yêu cầu cạnh ngắn hơn khớp với bậc độ phân giải; tuyến gốc chỉ chấp nhận các ánh xạ kích thước được hỗ trợ
input_reference	string	Tùy chọn	URL ảnh khung đầu tiên. Dùng URL HTTP(S) có thể tải xuống công khai để tương thích giữa các tuyến; không kết hợp với các đầu vào khung đầu tiên khác
prompt_extend	boolean	Gốc true; GMI giữ mặc định nhà cung cấp khi bỏ qua	Viết lại prompt. Tuyến gốc hiện không thể vô hiệu hóa nó một cách đáng tin cậy bằng false; GMI chuyển tiếp boolean rõ ràng
watermark	boolean	Mặc định gốc chính thức false; GMI giữ mặc định nhà cung cấp khi bỏ qua	Công tắc watermark
seed	integer	Ngẫu nhiên khi bỏ qua	Phạm vi cố định di động: 1–2147483647. Tuyến gốc cũng chấp nhận -1 cho ngẫu nhiên; 0 trên tuyến gốc bị bỏ qua trong quá trình tuần tự hóa. GMI chấp nhận 0–2147483647 và từ chối -1. Seed cố định không đảm bảo đầu ra giống hệt

Các bí danh kích thước gốc là 832x480, 480x832, 1280x720, 720x1280, 1920x1080, và 1080x1920 cho các trường hợp phong cảnh/chân dung thông thường. Một số ánh xạ kích thước vuông giảm thành 1:1; các kích thước được ánh xạ khác vẫn có thể không vượt qua xác thực tỷ lệ khung hình. Không dùng size để yêu cầu kích thước tùy ý.

Bảng tham số dành riêng cho tuyến

Trường GMI

Đây là các trường cấp cao nhất bổ sung vào bảng chung. Adapter GMI từ chối các trường không được nhận diện, bao gồm metadata, images, image_urls, audio, generate_audio, video_urls và reference_video.

Trường	Kiểu	Bắt buộc / mặc định	Hành vi
negative_prompt	string	Tùy chọn	Tối đa 500 ký tự
first_frame	string	Tùy chọn	URL ảnh HTTP(S) công khai; thay thế cho input_reference
last_frame	string	Tùy chọn	URL ảnh khung cuối HTTP(S) công khai; cũng cung cấp khung đầu tiên
reference_image	string hoặc string[]	Tùy chọn	1–10 URL ảnh tham chiếu HTTP(S) công khai; dùng mảng cho nhiều ảnh
audio_url	string	Tùy chọn	URL âm thanh tham chiếu HTTP(S) công khai; chịu sự xác thực phương tiện của nhà cung cấp

Chỉ dùng một trong hai: điều khiển khung hoặc ảnh tham chiếu trong một yêu cầu. metadata.input.media gốc không được dịch thành các trường này trên GMI.

Trường gốc Alibaba Cloud

Các đầu vào có cấu trúc gốc thuộc bên trong metadata. Gửi trực tiếp các đối tượng input hoặc parameters chính thức ở cấp cao nhất không phải là hợp đồng APIMaster. Luôn giữ prompt cấp cao nhất bắt buộc.

Trường	Kiểu	Bắt buộc / mặc định	Hành vi
generate_audio	boolean	Mặc định gốc chính thức true	Liệu đầu ra có chứa track âm thanh hay không; false được giữ nguyên
audio	boolean	Tùy chọn	Bí danh của generate_audio; chỉ cung cấp một
images	string[]	Tùy chọn	Được chuyển thành các mục phương tiện reference_image; đây không phải khung đầu/cuối có thứ tự. Không kết hợp với input_reference
metadata	object	Tùy chọn	Bao bọc input và parameters gốc; không thể thay đổi model
metadata.input	object	Tùy chọn	Vùng chứa đầu vào gốc
metadata.input.prompt	string	Tùy chọn	Ghi đè prompt gốc; ưu tiên chỉ dùng prompt cấp cao nhất
metadata.input.media	object[]	Tùy chọn	Bộ sưu tập phương tiện gốc, với type và url trong mỗi mục
metadata.input.media[].type	string	Bắt buộc cho mỗi mục	first_frame, last_frame, reference_image, reference_audio, file, link; reference_video hiện bị từ chối
metadata.input.media[].url	string	Bắt buộc cho mỗi mục	Vị trí phương tiện; nên dùng URL HTTP(S) công khai. URL tạm thời OSS chính thức yêu cầu ngữ cảnh tải lên thượng nguồn hợp lệ riêng; APIMaster không cung cấp ngữ cảnh tải lên đó
metadata.parameters	object	Tùy chọn	Vùng chứa tham số gốc; không được là null
metadata.parameters.resolution	string	720P	Chữ hoa 480P, 720P, 1080P
metadata.parameters.ratio	string	16:9	Tỷ lệ khung hình gốc bao gồm adaptive và 21:9
metadata.parameters.duration	integer	5	2–30; không -1
metadata.parameters.audio	boolean	Mặc định gốc chính thức true	Công tắc âm thanh đầu ra
metadata.parameters.prompt_extend	boolean	true	Phải giữ true cho file / link; false rõ ràng có hạn chế tuần tự hóa ở trên
metadata.parameters.watermark	boolean	Mặc định gốc chính thức false	Công tắc watermark
metadata.parameters.seed	integer	Ngẫu nhiên	-1 hoặc 0–2147483647; 0 có hạn chế tuần tự hóa ở trên

Các tùy chọn gốc cấp cao nhất ghi đè các tham số metadata tương ứng của chúng. input_reference cấp cao nhất thay thế mảng phương tiện gốc; images nối thêm các mục ảnh tham chiếu khi input_reference vắng mặt. Dùng một kiểu đầu vào và một kiểu tham số để tránh ghi đè ngoài ý muốn. Không dùng img_url, first_frame_url, last_frame_url hoặc audio_url cũ bên trong input gốc; adapter từ chối các trường phương tiện cũ đó cho Wan 3.0.

Ràng buộc phương tiện

Các quy tắc phương tiện gốc chính thức bên dưới cũng giải thích xác thực phía nhà cung cấp; việc adapter chấp nhận URL không chứng minh phương tiện hợp lệ.

Phương tiện	Giới hạn / ghi chú tích hợp
Khung đầu / cuối	Tối đa một mỗi loại; khung cuối yêu cầu khung đầu. Không trộn điều khiển khung với reference_image
Ảnh tham chiếu	Tối đa 10; JPEG/JPG, PNG không trong suốt, BMP hoặc WEBP; mỗi cạnh 240–8.000 px, tỷ lệ khung hình tối đa 8:1, tối đa 20 MB mỗi ảnh
Âm thanh tham chiếu	Gốc: tối đa 5, WAV/MP3, mỗi tệp 1–15 giây, kết hợp tối đa 15 giây, tối đa 15 MB mỗi tệp. GMI cung cấp một audio_url
Tệp / trang web	Chỉ gốc: tối đa một tệp hoặc một trang có thể đọc công khai; không kết hợp file và link. Định dạng tệp chính thức: DOCX, DOC, XLSX, XLS, PPTX, PPT, PDF, TXT, KEY, PAGES, NUMBERS, MD; tối đa 100 MB, với giới hạn 50 trang cho các định dạng có phân trang áp dụng. Giữ prompt_extend: true
Video tham chiếu	Có sẵn chính thức, nhưng hiện bị chặn bởi xác thực thanh toán gốc của APIMaster; không được cung cấp trên GMI. Không sử dụng các ví dụ chỉnh sửa hoặc mở rộng video từ API chính thức ở đây

Giới hạn phương tiện kết hợp gốc chính thức là 20 mục; các giới hạn riêng lẻ và kết hợp vẫn được áp dụng. URL dữ liệu Base64 của ảnh là một phần của định dạng đầu vào gốc chính thức, nhưng không được chấp nhận bởi xác thực URL của GMI. Ưu tiên URL HTTP(S) có thể tải xuống trên các tuyến.

Ví dụ

Văn bản-thành-video, các trường chung

curl "https://apimaster.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video-prime","prompt":"A paper boat drifting across a quiet pond at sunrise, gentle camera movement.","duration":5,"resolution":"720P","aspect_ratio":"16:9"}'

Khung đầu tiên, các trường chung

{"model":"wan3.0-video-prime","prompt":"The boat moves slowly forward, with soft ripples.","input_reference":"https://example.com/boat.png","duration":5,"resolution":"720P","aspect_ratio":"16:9"}

Khung đầu / cuối GMI

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","first_frame":"https://example.com/start.png","last_frame":"https://example.com/end.png","duration":5,"resolution":"720P","prompt_extend":false,"seed":0}

Khung đầu / cuối gốc và đầu ra im lặng

{"model":"wan3.0-video-prime","prompt":"Move smoothly from the first frame to the last frame.","duration":5,"resolution":"720P","generate_audio":false,"metadata":{"input":{"media":[{"type":"first_frame","url":"https://example.com/start.png"},{"type":"last_frame","url":"https://example.com/end.png"}]}}}

Ảnh và âm thanh tham chiếu gốc

{"model":"wan3.0-video-prime","prompt":"Animate the character in image 1, with the mood of audio 1.","duration":5,"resolution":"720P","metadata":{"input":{"media":[{"type":"reference_image","url":"https://example.com/character.png"},{"type":"reference_audio","url":"https://example.com/music.mp3"}]}}}

Thay thế URL phương tiện ví dụ bằng tệp công khai thực. Các ví dụ dành riêng cho tuyến yêu cầu tuyến khớp và vẫn chịu sự kiểm tra kết hợp thượng nguồn.

Phản hồi, thăm dò và tải xuống

Tạo trả về ID tác vụ APIMaster, ví dụ:

{"id":"task_example","task_id":"task_example","object":"video","model":"wan3.0-video-prime","status":"queued"}

Trường	Ý nghĩa
id / task_id	Mã định danh tác vụ APIMaster, không phải mã định danh tác vụ thượng nguồn
status	queued, in_progress, completed, failed
progress	Tiến độ được báo cáo; không đảm bảo hoàn thành
error.code / error.message	Chi tiết lỗi khi có
metadata.url	Địa chỉ nội dung được xác thực khi được trả về khi hoàn thành

Thăm dò mỗi 10–20 giây với cùng khóa API cho đến trạng thái kết thúc; thành công khi tạo chỉ có nghĩa là được chấp nhận. Tạo có thể mất vài phút. Thăm dò một tác vụ đã được chấp nhận thay vì tạo lặp lại các tác vụ trả phí.

curl "https://apimaster.ai/v1/videos/task_example" -H "Authorization: Bearer YOUR_API_KEY"
curl -L "https://apimaster.ai/v1/videos/task_example/content" \
  -H "Authorization: Bearer YOUR_API_KEY" -o wan-prime.mp4

Tải xuống và lưu video đã hoàn thành ngay lập tức; URL kết quả thượng nguồn có thể hết hạn. Thăm dò lặp lại không tạo thêm phí tạo.

Thanh toán và các lỗi thường gặp

Thanh toán theo giây ở độ phân giải được yêu cầu, với giá theo tuyến/tài khoản được hiển thị trên thẻ mô hình. Gửi sẽ giữ trước khoản phí ước tính. Hoàn thành gốc sử dụng thời lượng có thể tính phí được trả về và giá gửi đã đóng băng; GMI tuân theo hợp đồng thời lượng đã giữ trước. Các tác vụ thất bại giải phóng/hoàn lại đặt trước tạo của chúng. Tắt âm thanh không ngụ ý bậc rẻ hơn. Sử dụng nhật ký sử dụng cho số tiền cuối cùng.

Lỗi / triệu chứng	Hành động
duration must be an integer from 2 to 30	Dùng số nguyên rõ ràng; -1 không được tích hợp
unsupported Wan request field ...	Xóa một trường không được GMI hỗ trợ hoặc xác nhận quyền truy cập vào tuyến gốc khớp
unsupported aspect ratio	Dùng tỷ lệ phổ biến; 21:9 yêu cầu định tuyến gốc
reference video requires an input-duration quote	Xóa video tham chiếu; khả năng này hiện bị chặn
prompt is required / lỗi tải phương tiện	Thêm văn bản cấp cao nhất; dùng phương tiện hợp lệ, có thể tải xuống công khai
prompt_extend: false hoặc seed: 0 không có tác dụng trên tuyến gốc	Hạn chế tuần tự hóa hiện tại; dùng seed dương và không phụ thuộc vào việc vô hiệu hóa viết lại

Nguồn: thông tin mô hình chính thức, tham chiếu API gốc chính thức, và hướng dẫn sử dụng chính thức. Khả năng chính thức không có nghĩa là cùng một trường được cung cấp trên mọi tuyến APIMaster.