Wan

Wan (Tongyi Wanxiang) là dòng mô hình tạo video của Alibaba, được cung cấp bởi các kênh DashScope. Tác vụ đi qua cùng endpoint như mọi mô hình video khác — xem Tạo tác vụ và Lấy tác vụ. Trang này mô tả đầy đủ bộ chuyển đổi Wan 3.0: những trường yêu cầu nó đọc, cách dựng yêu cầu DashScope, quy tắc nguyên liệu, cách đọc bản ghi tác vụ và cách tính phí theo giây.

Tạo video là bất đồng bộ: gửi yêu cầu, giữ task_id, hỏi lại mỗi 10–15 giây, rồi tải về khi trạng thái là SUCCESS.

Mô hình

ID mô hình	Độ phân giải	Thời lượng	Ghi chú
`wan3.0-video`	`480P`, `720P`, `1080P`	2–30 giây, hoặc `-1` (thông minh)	Bản tiêu chuẩn: văn bản thành video, khung đầu/cuối và nguyên liệu tham chiếu đa phương tiện
`wan3.0-video-prime`	`480P`, `720P`, `1080P`	2–30 giây, hoặc `-1` (thông minh)	Biến thể nhanh hơn với cùng khả năng

Cả hai mặc định 1080P và 5 giây khi yêu cầu không đặt. Cả hai hỗ trợ văn bản thành video, ảnh thành video với khung đầu hoặc khung đầu và cuối, ảnh/video/âm thanh tham chiếu, chỉnh sửa và kéo dài video. ID mô hình là giá trị GET /v1/models trả về; mô hình tài khoản bạn dùng được và giá của chúng do console RouteAPI quy định.

Kênh cũng phục vụ các mô hình Wan 2.x cũ (wan2.7-i2v, wan2.7-t2v, wan2.5-i2v-preview, wan2.2-*, wanx2.1-*) với quy tắc khác, không nằm trong phạm vi trang này.

Cách khung chung được ánh xạ

Trường khung	Bộ chuyển đổi Wan 3.0 làm gì
`prompt`	Gửi làm `input.prompt`. Như mọi yêu cầu tác vụ, prompt rỗng bị từ chối trước khi gửi (`400`)
`image` / `images`	Khung đầu là `image` nếu được đặt, ngược lại là phần tử không rỗng đầu tiên của `images`; khung cuối là phần tử không rỗng thứ hai của `images`. Các ảnh sau hai ảnh đầu bị bỏ qua
`input_reference`	Dạng viết tắt một ảnh: thay mảng `images` bằng một URL, nhưng `image` cấp cao nhất vẫn được ưu tiên cho khung đầu
`resolution`	Gửi làm `parameters.resolution`, chuyển chữ hoa và thêm `P` nếu cần
`ratio`	Gửi làm `parameters.ratio`, chuyển chữ thường
`size`	Được gộp vào `resolution` và `ratio` rồi bị bỏ. `1920x1080` và `19201080` đều được nhận; kích thước dạng `` ngoài bảng trả `400`, còn bậc trần như `720p` được dùng làm độ phân giải
`duration`	Gửi làm `parameters.duration`. Giá trị thiếu trở thành 5
`seconds`	Phân tích thành thời lượng nguyên khi không có `duration`
`generate_audio`	Gửi làm `parameters.audio`; `false` tường minh vẫn được chuyển tiếp
`metadata`	Được gộp đè lên yêu cầu đã dựng, nên `metadata.parameters.` và `metadata.input.` thắng giá trị đã ánh xạ

Khi gửi cả hai, resolution / ratio tường minh thắng giá trị suy ra từ size; size luôn bị bỏ khỏi body gửi upstream. Bộ chuyển đổi sau đó gửi input, parameters và model tới endpoint tổng hợp video của DashScope; bạn không tự gọi endpoint đó.

Vì body dùng cấu trúc của DashScope, các giá trị tương tự cũng có thể đặt trong metadata:

{
  "metadata": {
    "input": { "negative_prompt": "blurry, low quality" },
    "parameters": { "duration": 10, "resolution": "720p", "ratio": "9:16" }
  }
}

metadata không thể đổi mô hình: metadata.model khác mô hình upstream đã giải quyết sẽ bị từ chối với 400.

Tham số

Các trường sau ghi được ở cấp cao nhất của body. Khóa riêng của mô hình đặt trong metadata.

Trường	Kiểu	Giá trị	Ghi chú
`model`	string	`wan3.0-video`, `wan3.0-video-prime`	Bắt buộc
`prompt`	string	—	Bắt buộc và không rỗng. Ở chế độ tham chiếu, gọi nguyên liệu là “image 1”, “video 1”, “audio 1”
`resolution`	string	`480P`, `720P`, `1080P`	Không phân biệt hoa thường, `P` ở cuối có thể bỏ. Mặc định `1080P`
`ratio`	string	`adaptive`, `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`	Không phân biệt hoa thường. Khi bỏ trống, DashScope áp dụng `adaptive`
`size`	string	`1280*720`, `1280x720` hoặc `720p`	Gộp vào `resolution` và `ratio` rồi bị bỏ. Chỉ nhận kích thước có trong bảng của bộ chuyển đổi
`duration`	integer	2–30	Số giây đầu ra. Mặc định 5. Giá trị âm hoặc lớn hơn 3600 bị kiểm tra tác vụ chung từ chối; `-1` (thời lượng thông minh) chỉ dùng được trong `metadata.parameters`
`seconds`	string	chuỗi số nguyên	Dùng thay `duration` khi `duration` vắng mặt hoặc bằng `0`. Giá trị không nguyên trả `400`
`image`	string	URL	Ảnh khung đầu đơn lẻ; nó được ưu tiên hơn `images` cho khung đầu
`images`	array	Danh sách URL	1 ảnh = khung đầu; 2 ảnh = khung đầu rồi khung cuối
`input_reference`	string	URL	Thay `images` bằng một URL khung đầu; `image` cấp cao nhất vẫn được ưu tiên
`generate_audio`	boolean	`true` / `false`	Gửi làm `parameters.audio`; `false` tường minh được chuyển tiếp là `false`
`metadata`	object	`input` / `parameters` của DashScope	Ghi đè các giá trị đã ánh xạ; xem bên dưới

Nếu size là cặp RỘNG*CAO, nó phải có trong bảng của bộ chuyển đổi: 480P nhận 832*480, 480*832, 624*624; 720P nhận 1280*720, 720*1280, 960*960, 1088*832, 832*1088; 1080P nhận 1920*1080, 1080*1920, 1440*1440, 1632*1248, 1248*1632. Tỷ lệ được rút gọn từ cặp và chỉ giữ lại nếu khớp một trong các giá trị hỗ trợ; nếu không, yêu cầu để DashScope dùng tỷ lệ mặc định.

Tham số metadata

metadata tương ứng với các đối tượng input / parameters của DashScope. Mọi khóa dưới đây đều tùy chọn.

Khóa metadata	Kiểu	Ghi chú
`input.media`	array	Danh sách nguyên liệu gồm các mục `{"type", "url"}`. Khi có, trường ảnh cấp cao nhất không được dùng
`input.prompt`	string	Thay prompt cấp cao nhất khi gửi upstream, nhưng kiểm tra chung vẫn yêu cầu `prompt` cấp cao nhất
`input.audio_url`	string	Cách viết tắt để thêm một mục `reference_audio`
`input.negative_prompt`	string	Prompt phủ định
`input.template`	string	Mẫu hiệu ứng DashScope, chuyển tiếp nguyên trạng
`parameters.resolution`	string	Như `resolution` cấp cao nhất
`parameters.ratio`	string	Như `ratio` cấp cao nhất
`parameters.size`	string	Như `size` cấp cao nhất
`parameters.duration`	integer	`-1` là thời lượng thông minh, ngược lại 2–30
`parameters.audio`	boolean	Như `generate_audio`
`parameters.seed`	integer	`-1` hoặc 0–2147483647. `0` được giữ làm giá trị tường minh; cùng seed không đảm bảo kết quả giống hệt
`parameters.watermark`	boolean	Watermark phía nhà cung cấp; mặc định tắt
`parameters.prompt_extend`	boolean	Nhận nhưng không có tác dụng — viết lại prompt luôn bật (xem bên dưới)

Giá trị trong metadata.parameters.* thắng các giá trị tương ứng ở cấp cao nhất. Khóa không nhận ra trong metadata bị bỏ qua, còn khóa sai kiểu trả 400 trước khi có bất kỳ khoản tạm giữ nào.

prompt_extend không thể tắt. Cấp cao nhất không có trường này, nên prompt_extend ở cấp cao nhất bị bỏ qua hoàn toàn; trong metadata.parameters, bộ chuyển đổi luôn bắt đầu từ true và lưu giá trị vào bool không phải con trỏ có omitempty, nên false bị bỏ khi gửi tới DashScope và giá trị mặc định của nhà cung cấp (bật) được áp dụng. Chỉ gửi nếu bạn muốn nhắc lại giá trị mặc định; nó không thay đổi gì.

Nguyên liệu đầu vào

Wan 3.0 nhận nguyên liệu qua input.media, một mảng các mục {"type": "...", "url": "..."}. Bộ chuyển đổi dựng nó từ các trường ảnh cấp cao nhất và gộp thêm những gì bạn truyền tường minh:

`type`	Ý nghĩa	Giới hạn (DashScope)
`first_frame`	Khung đầu của video	1
`last_frame`	Khung cuối của video; cần có khung đầu	1
`reference_image`	Ảnh tham chiếu cho chủ thể hoặc phong cách	10
`reference_video`	Video tham chiếu để tạo, chỉnh sửa hoặc kéo dài	5, tổng cộng 15 giây
`reference_audio`	Âm thanh tham chiếu. `input.audio_url` được thêm với kiểu này	5, tổng cộng 15 giây

Mảng media bạn truyền tường minh trong metadata.input.media được giữ nguyên; khi không có, bộ chuyển đổi dựng từ các trường ảnh cấp cao nhất theo thứ tự first_frame, last_frame. Đường dự phòng này cũng đọc các khóa cũ metadata.input.img_url / first_frame_url / last_frame_url, và metadata.input.audio_url luôn thêm một mục reference_audio. Cả bốn trường cũ được gộp vào media rồi xóa — Wan 3.0 chỉ hiểu media.

Số lượng và thời lượng trong bảng trên là quy tắc của DashScope. RouteAPI không kiểm tra trước; vi phạm bị upstream từ chối và hoàn tiền — có thể là lỗi fail_to_fetch_task, có thể là tác vụ FAILURE — chứ không phải 400 cục bộ.

Quy tắc nguyên liệu:

URL nguyên liệu phải là địa chỉ http(s) công khai tải được mà không cần đăng nhập. Ảnh cũng có thể dùng data:image/png;base64,....
Giới hạn từng nguyên liệu: ảnh JPEG / JPG / PNG (không kênh alpha) / BMP / WEBP, mỗi cạnh 240–8000 px, tỷ lệ khung hình tối đa 8:1, tối đa 20 MB; video mp4 / mov, mỗi đoạn 1–15 giây, tối thiểu 16 fps, mỗi cạnh 240–4096 px, tối đa 100 MB; âm thanh wav / mp3, mỗi đoạn 1–15 giây, tối đa 15 MB.
Chế độ khung đầu/cuối và chế độ nguyên liệu tham chiếu loại trừ nhau. Trộn khung với mục reference_* trong cùng một mảng media bị upstream từ chối: tác vụ được hoàn tiền.
reference_image, reference_video và reference_audio kết hợp tự do.
Trong prompt, gọi nguyên liệu theo số thứ tự — “image 1”, “video 1”, “audio 1” — đếm theo loại theo thứ tự xuất hiện trong media.

Hai quy tắc được kiểm tra cục bộ, trước khi gửi, nên không chạm tới nhà cung cấp hay ví tiền:

metadata.input.audio_url cùng với mục first_frame hoặc last_frame bị từ chối với 400 và thông báo wan3 does not support audio_url together with first/last frame images. Kiểm tra chỉ xét input.audio_url; mục reference_audio đặt trực tiếp trong media cạnh khung sẽ do DashScope chặn (tác vụ FAILURE, hoàn tiền).
Sau khi gộp metadata, yêu cầu có prompt rỗng và mảng media rỗng bị từ chối với 400 (wan3 requires prompt or input.media). Trên thực tế kiểm tra tác vụ chung đã từ chối prompt rỗng, nên prompt luôn bắt buộc.

Văn bản thành video

Chỉ gửi prompt và các tham số video:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "An orange cat walking on a rooftop, cinematic lighting",
    "resolution": "480P",
    "ratio": "16:9",
    "duration": 2
  }'

Khung đầu và khung cuối

Đặt ảnh trong mảng images cấp cao nhất: một ảnh là khung đầu, hai ảnh là khung đầu rồi khung cuối theo thứ tự đó.

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "The scene shifts naturally from morning to sunset while the camera moves smoothly",
    "images": [
      "https://cdn.example.com/first.jpg",
      "https://cdn.example.com/last.jpg"
    ],
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 5
  }'

Cũng có thể viết rõ các khung trong metadata.input.media với type tường minh; last_frame luôn phải gửi kèm first_frame.

Ảnh + video + âm thanh tham chiếu

Với nguyên liệu tham chiếu, ghi từng mục trong metadata.input.media. Khi đã có media, các trường ảnh cấp cao nhất bị bỏ qua.

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "The character in image 1 performs the motion from video 1, dancing to the rhythm of audio 1",
    "resolution": "720P",
    "ratio": "adaptive",
    "duration": 8,
    "metadata": {
      "input": {
        "media": [
          { "type": "reference_image", "url": "https://cdn.example.com/character.jpg" },
          { "type": "reference_video", "url": "https://cdn.example.com/motion.mp4" },
          { "type": "reference_audio", "url": "https://cdn.example.com/music.mp3" }
        ]
      }
    }
  }'

Yêu cầu có mục reference_video tạm giữ 30 giây khi gửi bất kể thời lượng yêu cầu, vì lúc đó chưa biết độ dài đầu ra cuối cùng — xem Tính phí.

Chỉnh sửa và kéo dài video

Cả hai chế độ đều truyền video nguồn qua reference_video và diễn đạt ý định trong prompt.

Chỉnh sửa — ví dụ “chuyển toàn bộ video 1 sang phong cách đất sét”. Gửi ratio: "adaptive" để đầu ra giữ tỷ lệ của nguồn.
Kéo dài — ví dụ “kéo dài video 1 về phía trước, giữ chuyển động nhân vật và phong cách camera nhất quán”. ratio phải là adaptive. Đặt duration bằng độ dài nguồn cộng phần kéo dài: kéo dài video 5 giây thêm 2 giây thì điền 7. Cũng có thể dùng -1 để mô hình tự quyết.

Khi có video đầu vào, độ dài video nguồn cộng độ dài đầu ra không được vượt 30 giây. DashScope áp dụng giới hạn này; yêu cầu vi phạm sẽ thất bại và được hoàn tiền.

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "Convert video 1 entirely into a claymation style",
    "resolution": "480P",
    "ratio": "adaptive",
    "duration": 2,
    "metadata": {
      "input": {
        "media": [ { "type": "reference_video", "url": "https://cdn.example.com/input.mp4" } ]
      }
    }
  }'

Để kéo dài cùng đoạn 5 giây thêm 2 giây, chỉ đổi prompt và thời lượng:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "Extend video 1 forward by two seconds, keeping the character motion and camera style consistent",
    "resolution": "480P",
    "ratio": "adaptive",
    "duration": 7,
    "metadata": {
      "input": {
        "media": [ { "type": "reference_video", "url": "https://cdn.example.com/input.mp4" } ]
      }
    }
  }'

Thời lượng thông minh

Với thời lượng thông minh, mô hình chọn độ dài. Gửi -1 trong metadata.parameters.duration; duration cấp cao nhất âm bị kiểm tra tác vụ chung từ chối với invalid_seconds.

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "An orange cat walking on a rooftop, cinematic lighting",
    "resolution": "480P",
    "ratio": "16:9",
    "metadata": { "parameters": { "duration": -1 } }
  }'

Tác vụ thời lượng thông minh tạm giữ 30 giây khi gửi và quyết toán theo độ dài đầu ra thực tế khi hoàn tất.

Truy vấn tác vụ

curl https://api.routeapi.ai/v1/video/generations/task_FQvcRkHE9wjSWwyISDcrWCKoqCPNdkCx \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "code": "success",
  "message": "",
  "data": {
    "id": 4512,
    "created_at": 1792412645,
    "updated_at": 1792412780,
    "task_id": "task_FQvcRkHE9wjSWwyISDcrWCKoqCPNdkCx",
    "platform": "17",
    "user_id": 1024,
    "group": "default",
    "channel_id": 18,
    "quota": 50000,
    "action": "textGenerate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://dashscope-result.oss.example/video.mp4",
    "submit_time": 1792412645,
    "start_time": 1792412650,
    "finish_time": 1792412780,
    "properties": {
      "input": "",
      "origin_model_name": "wan3.0-video",
      "upstream_model_name": "wan3.0-video"
    },
    "data": {
      "request_id": "42a9c287-db7b-9edb-b613-xxxxxxxx",
      "output": {
        "task_id": "dd40fcb4-34f4-4292-a9e0-xxxxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-result.oss.example/video.mp4",
        "orig_prompt": "An orange cat walking on a rooftop, cinematic lighting"
      },
      "usage": {
        "video_count": 1,
        "duration": 2,
        "input_video_duration": 0,
        "output_video_duration": 2,
        "fps": 30,
        "SR": 480,
        "ratio": "16:9"
      }
    }
  }
}

Các trường bên ngoài do RouteAPI tạo. Hãy tin data.status; data.progress với Wan chỉ là mốc giai đoạn thô (20% xếp hàng, 30% đang tạo, 100% xong), không phải phần trăm thực của nhà cung cấp. data.quota là số đã trừ đến hiện tại — sau khi tác vụ thành công, nó phản ánh số đã quyết toán. data.action là generate khi yêu cầu có trường ảnh cấp cao nhất (image, images hoặc input_reference), ngược lại là textGenerate.

data.data là payload tác vụ gốc của DashScope, lưu nguyên trạng. Các trường đáng đọc:

Trường	Ý nghĩa
`data.data.output.task_id`	ID tác vụ DashScope, khác `data.task_id` bên ngoài
`data.data.output.video_url`	URL video của nhà cung cấp; cùng giá trị với `data.result_url` bên ngoài
`data.data.output.orig_prompt`	Prompt DashScope đã nhận
`data.data.usage.output_video_duration`	Số giây đầu ra thực tế — đây là số giây được tính phí
`data.data.usage.input_video_duration`	Số giây video đầu vào; miễn phí. `0` với văn bản thành video
`data.data.usage.duration`	Số giây đầu vào + đầu ra; chỉ để tham khảo, không bao giờ dùng để quyết toán
`data.data.usage.SR`	Bậc độ phân giải đầu ra thực tế (480, 720, 1080); dùng để quyết toán
`data.data.usage.fps`	Tốc độ khung hình đầu ra, 30 với các mô hình này
`data.data.usage.ratio`	Tỷ lệ khung hình thực tế. Với `adaptive` là tỷ lệ của nguyên liệu, ví dụ `427:240`

data.data có thể chưa đầy đủ cho đến khi tác vụ kết thúc, nên đánh giá hoàn tất bằng data.status, không phải sự có mặt của usage.

Trạng thái: NOT_START và QUEUED là tiếp tục hỏi, IN_PROGRESS là đang tạo, SUCCESS là tải về, FAILURE là đọc fail_reason — khoản tạm giữ đã được hoàn.

Tải video

data.result_url trỏ tới tệp do Alibaba lưu trữ. URL này là tạm thời — Alibaba cho hết hạn theo lịch riêng, nên hãy tải sớm — hoặc truyền qua RouteAPI, cách này không phụ thuộc thời hạn còn lại của URL:

curl -L -o out.mp4 \
  https://api.routeapi.ai/v1/videos/task_FQvcRkHE9wjSWwyISDcrWCKoqCPNdkCx/content \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Endpoint content chỉ phục vụ tác vụ đã hoàn tất của chính người gọi: tác vụ chưa xong trả 400 kèm trạng thái hiện tại trong thông báo, task_id không xác định hoặc của người khác trả 404, lỗi lấy dữ liệu từ nhà cung cấp trả 502. Danh sách lỗi đầy đủ xem tại Lấy tác vụ. result_url còn hạn cũng có thể dùng trực tiếp làm reference_video hoặc reference_image cho yêu cầu tiếp theo.

Ánh xạ trạng thái

Trạng thái DashScope	Trạng thái bản ghi tác vụ
`PENDING`	`QUEUED`
`RUNNING`	`IN_PROGRESS`
`SUCCEEDED`	`SUCCESS`
`FAILED`, `CANCELED`, `UNKNOWN`	`FAILURE`

Tính phí

Wan 3.0 tính phí theo giây đầu ra, nhân theo độ phân giải. Giá trên console là đơn giá mỗi giây cho 480P; các bậc khác bằng đơn giá đó nhân hệ số độ phân giải của mô hình, mặc định 480P : 720P : 1080P = 1 : 2 : 4.

Cả khoản tạm giữ và khoản quyết toán dùng cùng công thức:

base quota        = model price (per 480P second) × group ratio
reserved quota    = base quota × reserved seconds × resolution ratio
settled quota     = min(base quota × output seconds × effective ratio, reserved quota)

Hệ số hiệu lực là hệ số của bậc yêu cầu, hoặc — khi DashScope báo SR thấp hơn yêu cầu — hệ số của bậc thấp hơn. Nó không bao giờ cao hơn bậc yêu cầu.

Tạm giữ và quyết toán:

Yêu cầu	Tạm giữ khi gửi	Khi hoàn tất
Thời lượng rõ ràng, không có `reference_video`	số giây yêu cầu	số giây đầu ra thực tế
Có mục `reference_video`	30 giây	số giây đầu ra thực tế, hoàn phần chênh lệch
`metadata.parameters.duration: -1` (thời lượng thông minh)	30 giây	số giây đầu ra thực tế, hoàn phần chênh lệch

Quy tắc quyết toán đã kiểm chứng trong bộ chuyển đổi:

Chỉ tính phí usage.output_video_duration. Số giây video đầu vào, ảnh và âm thanh tham chiếu, khung đầu/cuối đều miễn phí, và việc tạo âm thanh không đổi giá.
Đơn giá là bản chốt lúc gửi. Thay đổi giá trên console khi tác vụ đang chạy không ảnh hưởng; khoản tạm giữ giữ nguyên.
Quyết toán chỉ hoàn. Tác vụ báo nhiều giây hơn mức tạm giữ, SR cao hơn, hoặc usage sai định dạng sẽ giữ khoản tạm giữ thay vì trừ thêm; tác vụ thành công thiếu usage cũng giữ khoản tạm giữ.
Tác vụ thất bại — bị kiểm duyệt từ chối, nhà cung cấp quá thời gian, hủy — hoàn khoản tạm giữ. 400 bị từ chối trước khi gửi và không bao giờ tính phí.
Yêu cầu tạm giữ 30 giây cần số dư hoặc quota Key đủ để phủ khoản đó, nếu không lần gửi bị từ chối với 403 insufficient_user_quota.

Phản hồi gửi kèm header X-New-Api-Other-Ratios chứa các hệ số đã áp dụng, ví dụ {"resolution-1080P":4,"seconds":5} cho yêu cầu 1080P 5 giây. Với yêu cầu có video tham chiếu hoặc thời lượng thông minh, seconds là 30.

Ví dụ (giá chỉ là giả định; dùng console cho giá thực). Giả sử mô hình giá $0.05 mỗi giây 480P, nên 720P là $0.10 và 1080P là $0.20 theo bảng 1 : 2 : 4 mặc định, tỷ lệ nhóm là 1:

Yêu cầu 1080P, duration: 5. Tạm giữ: 0.20 × 5 = $1.00.
DashScope báo usage.SR: 720 và output_video_duration: 5, tức đầu ra thấp hơn một bậc. Quyết toán: 0.10 × 5 = $0.50, và $0.50 được hoàn.
Nếu báo SR: 1080 trong 5 giây, khoản trừ vẫn là $1.00 — quyết toán không bao giờ vượt khoản tạm giữ.

Ví dụ thứ hai: 480P với video nguồn 2 giây, duration: 2. Vì có reference_video, khoản tạm giữ là 30 × $0.05 = $1.50; đầu ra thực tế 2 giây nên quyết toán là 2 × $0.05 = $0.10, và $1.40 được hoàn.

Giới hạn và lỗi

Lỗi tham số bị chặn trước khi gửi: trả 400, không gửi lên upstream và không tính phí.

Trạng thái	Mã	Ý nghĩa
400	`invalid_request`	Thiếu hoặc rỗng `prompt` (`prompt is required`); `audio_url` cùng khung đầu/cuối (`wan3 does not support audio_url together with first/last frame images`); prompt và media đều rỗng; trường `metadata` sai kiểu; `metadata.model` khác mô hình đã giải quyết (`can't change model with metadata`)
400	`invalid_request`	Lỗi kiểm tra tham số — xem bảng thông báo bên dưới
400	`invalid_json`	Body không phân tích được
400	`invalid_seconds`	`duration` / `seconds` cấp cao nhất âm hoặc lớn hơn 3600 (`seconds must be between 1 and 3600`)
400	`missing_model`	Body không có `model` (`model field is required`)
400	`task_not_exist`	`task_id` không xác định hoặc thuộc tài khoản khác
403	`insufficient_user_quota`	Số dư hoặc quota Key không phủ khoản tạm giữ; không gửi gì
429	—	Năng lực upstream cạn; thông điệp được thay bằng `Upstream load is saturated, please try again later`
500	`build_request_failed`, `do_request_failed`, `invalid_response`	Chuyển đổi thất bại, upstream không truy cập được, hoặc DashScope không trả ID tác vụ
trạng thái upstream	`ali_api_error`	DashScope trả mã và thông báo lỗi trong body phản hồi
trạng thái upstream	`fail_to_fetch_task`	DashScope từ chối gửi; mã HTTP là mã của DashScope

Các thông báo 400 thường gặp từ kiểm tra Wan 3.0, đúng nguyên văn:

`message`	Nguyên nhân
`invalid duration: 40, wan3 supports -1 or 2-30`	Thời lượng ngoài 2–30 và không phải `-1`
`invalid resolution: 4KP, wan3 supports 480P, 720P, 1080P`	Độ phân giải ngoài các bậc hỗ trợ (hiển thị sau khi chuyển chữ hoa và thêm `P`)
`invalid ratio: 1:2, wan3 supports adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16`	Tỷ lệ ngoài danh sách hỗ trợ
`invalid seed: 3000000000, wan3 supports -1 or 0-2147483647`	Seed ngoài `-1` hoặc 0–2147483647
`invalid size: 1000*1000`	Kích thước `RỘNG*CAO` không có trong bảng
`wan3 does not support audio_url together with first/last frame images`	Khung hình cùng âm thanh tham chiếu qua `input.audio_url`
`wan3 requires prompt or input.media`	Sau khi gộp metadata không có prompt lẫn media
`can't change model with metadata`	`metadata.model` khác mô hình upstream đã giải quyết
`convert seconds to int failed: ...`	`seconds` không phải chuỗi số nguyên
`seconds must be between 1 and 3600`	Thời lượng cấp cao nhất âm hoặc quá lớn; dùng `metadata.parameters.duration` cho `-1`

Lỗi sau khi gửi — kiểm duyệt, nguyên liệu không tải được, tổ hợp nguyên liệu không hợp lệ, đầu vào + đầu ra quá 30 giây — không trả về dưới dạng lỗi HTTP. Chúng xuất hiện trên bản ghi tác vụ với trạng thái FAILURE và fail_reason, và khoản tạm giữ được hoàn.

Khác biệt so với API DashScope

Endpoint khác. RouteAPI không cung cấp /api/v1/services/aigc/video-generation/video-synthesis; trỏ Base URL của SDK DashScope vào chúng tôi sẽ không hoạt động.
Các đối tượng input / parameters gốc của DashScope đặt trong metadata.input / metadata.parameters. Các tham số chung (prompt, resolution, ratio, size, duration, images, generate_audio) cũng ghi được ở cấp cao nhất và được ánh xạ tự động.
task_id trả về là ID của RouteAPI, không phải của DashScope. ID của DashScope nằm trong data.data.output.task_id.
Viết lại prompt (prompt_extend) luôn bật và không thể tắt.
Các trường ảnh cũ theo mô hình (img_url, first_frame_url, last_frame_url, audio_url) bị bỏ; chỉ input.media tới được nhà cung cấp.
Không hỗ trợ thông báo callback — hãy hỏi endpoint tác vụ.
Tính phí theo giây đầu ra nhân hệ số độ phân giải; cách tính theo lượt hoặc theo bậc của nhà cung cấp không áp dụng.

Script đầy đủ

Cần bash, curl và jq.

#!/usr/bin/env bash
set -euo pipefail
: "${ROUTEAPI_KEY:?set ROUTEAPI_KEY first}"
BASE="${ROUTEAPI_BASE:-https://api.routeapi.ai}"
AUTH="Authorization: Bearer $ROUTEAPI_KEY"

TASK_ID=$(curl -sS -X POST "$BASE/v1/video/generations" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"model":"wan3.0-video","prompt":"An orange cat walking on a rooftop, cinematic lighting","resolution":"480P","ratio":"16:9","duration":2}' \
  | jq -er .task_id)

echo "task: $TASK_ID"

for _ in $(seq 1 60); do
  RESP=$(curl -sS "$BASE/v1/video/generations/$TASK_ID" -H "$AUTH")
  STATUS=$(printf '%s' "$RESP" | jq -r .data.status)
  echo "status: $STATUS $(printf '%s' "$RESP" | jq -r .data.progress)"

  case "$STATUS" in
    SUCCESS)
      echo "billed seconds: $(printf '%s' "$RESP" | jq -r .data.data.usage.output_video_duration)"
      curl -sSL -o "$TASK_ID.mp4" "$BASE/v1/videos/$TASK_ID/content" -H "$AUTH"
      echo "saved $TASK_ID.mp4"
      exit 0
      ;;
    FAILURE)
      echo "failed: $(printf '%s' "$RESP" | jq -r .data.fail_reason)"
      exit 1
      ;;
  esac

  sleep 15
done

echo "timed out waiting for the task"
exit 1