Tạo tác vụ video

Tạo video trên RouteAPI là một API tác vụ bất đồng bộ. Bạn gửi yêu cầu, nhận task_id, thăm dò tác vụ cho đến khi đạt trạng thái kết thúc, rồi tải video về. Mọi mô hình video trên nền tảng — Seedance, Sora, Veo, Wan, Kling, Hailuo, Vidu và các mô hình khác — đều được gọi qua cùng các endpoint, vì RouteAPI chuyển yêu cầu của bạn sang dạng mà upstream đã chọn mong đợi.

Mô hình video xuất hiện trong GET /v1/models; supported_endpoint_types hiển thị openai-video với các kênh phục vụ theo định dạng video OpenAI, và trang mô hình trong console có thể đặt giá trị này cho từng mô hình. Dù thế nào, hãy lấy ID mô hình từ danh sách đó — xem Mô hình. Tham số riêng của từng mô hình được mô tả theo nhà cung cấp: Seedance, Hailuo, Wan. Phương ngữ OpenAI/Sora của cùng API được mô tả tại Định dạng video OpenAI.

Endpoint

Phương thức	Đường dẫn	Mục đích	Tài liệu
`POST`	`/v1/video/generations`	Gửi tác vụ tạo video	Trang này
`GET`	`/v1/video/generations/{task_id}`	Đọc bản ghi tác vụ	Lấy tác vụ video
`POST`	`/v1/videos`	Gửi tác vụ tạo video (phương ngữ OpenAI)	Định dạng video OpenAI
`GET`	`/v1/videos/{task_id}`	Đọc tác vụ dưới dạng đối tượng video OpenAI	Định dạng video OpenAI
`POST`	`/v1/videos/{video_id}/remix`	Tạo tác vụ dẫn xuất từ video có sẵn	Định dạng video OpenAI
`GET`	`/v1/videos/{task_id}/content`	Tải byte của video đã hoàn thành	Lấy tác vụ video

POST /v1/video/generations và POST /v1/videos là hai đường dẫn đến cùng một thao tác tác vụ với phương ngữ yêu cầu và phản hồi khác nhau. Phản hồi gửi ở cả hai đều là đối tượng video OpenAI; các endpoint GET khác nhau (bản ghi tác vụ so với đối tượng video), vì vậy hãy ghép mỗi đường dẫn gửi với GET tương ứng.

Tác vụ diễn ra thế nào

Gửi — gửi prompt và mô hình đến POST /v1/video/generations (hoặc POST /v1/videos) và lưu task_id trả về. Chi phí ước tính được giữ trước từ số dư của bạn tại bước này.
Thăm dò — gọi endpoint GET tương ứng mỗi 10–15 giây. Việc tạo thường mất từ một đến vài phút; độ phân giải cao hơn và thời lượng dài hơn sẽ lâu hơn.
Hoàn tất — khi trạng thái báo thành công, tải video hoặc đọc URL của nó. Nếu tác vụ thất bại hoặc không bao giờ đạt trạng thái kết thúc, khoản đã giữ trước sẽ được hoàn lại.

Gửi tác vụ

POST /v1/video/generations

Các trường yêu cầu

Mọi mô hình video đều chấp nhận khung chung này. Tùy chọn riêng của mô hình đặt trong metadata; các trang nhà cung cấp liệt kê những khóa mà mỗi adapter thực sự đọc.

Trường	Kiểu	Bắt buộc	Mô tả
`model`	string	Có	ID mô hình từ `GET /v1/models`
`prompt`	string	Có	Prompt văn bản. Prompt thiếu, rỗng hoặc chỉ có khoảng trắng bị từ chối với `400`
`image`	string	Không	Một ảnh (URL hoặc Base64/data URI). Được xử lý như phần tử đầu của `images`
`images`	string[]	Không	Ảnh tham chiếu / khung đầu. Ý nghĩa phụ thuộc vào mô hình
`size`	string	Không	Gợi ý kích thước hoặc độ phân giải như `1280x720` hay `720p`, tùy mô hình
`duration`	integer	Không	Thời lượng tính bằng giây. RouteAPI từ chối giá trị âm và giá trị lớn hơn 3600
`seconds`	string	Không	Dạng chuỗi cũ của thời lượng. Các mô hình đọc trường này dùng nó thay cho `duration`
`input_reference`	string	Không	Trường ảnh tham chiếu kiểu OpenAI, được các adapter hỗ trợ đọc (ví dụ Sora và Wan)
`ratio`	string	Không	Tỷ lệ khung hình như `16:9` hoặc `9:16`; adapter Seedance đọc trường này
`resolution`	string	Không	Mức độ phân giải đầu ra như `720p` hoặc `1080p`; adapter Seedance đọc trường này
`generate_audio`	boolean	Không	Tạo nhạc nền. Trên Seedance, `false` tường minh được chuyển tiếp chứ không bị bỏ
`metadata`	object	Không	Tham số riêng của nhà cung cấp. Với Seedance, khi trùng tên, giá trị trong `metadata` thắng giá trị ở cấp cao nhất

Các trường cấp cao nhất mà RouteAPI không nhận ra sẽ bị bỏ qua; hãy đặt tham số riêng của mô hình vào metadata.

Các endpoint gửi cũng nhận body multipart/form-data: trường form dạng vô hướng ánh xạ tới cùng tên, và tệp được tải trực tiếp (ví dụ input_reference cho Sora). Trường form không nhận ra sẽ trở thành mục metadata.

Ví dụ gửi

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0-fast",
    "prompt": "An orange cat stretching on a windowsill at sunrise",
    "duration": 5,
    "resolution": "720p",
    "ratio": "16:9",
    "generate_audio": false
  }'

Phản hồi gửi

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0-fast",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

task_id (và bí danh id) là ID tác vụ RouteAPI; mọi lệnh gọi sau đó đều dùng nó. ID tác vụ của nhà cung cấp upstream không phải giá trị bạn dùng để thăm dò — nếu có thể thấy, nó nằm trong payload upstream đã lưu (data.data trên bản ghi tác vụ).

Gửi thành công cũng trả về header X-New-Api-Other-Ratios chứa các hệ số tính phí đã áp dụng — ví dụ {"seconds":5,"size":1} cho Sora, hoặc {"video_input":0.608695652174} cho yêu cầu Seedance có đầu vào video. Header này hữu ích khi đối soát khoản phí.

Lỗi ở bước gửi

Sau khi được định tuyến, các endpoint tác vụ trả về theo cấu trúc lỗi của tác vụ:

{ "code": "invalid_request", "message": "prompt is required", "data": null }

Trạng thái	Mã	Ý nghĩa
400	`invalid_request`	Thiếu hoặc để trống `prompt`, trường `metadata` sai kiểu, hoặc body không phân tích được
400	`invalid_json`	JSON không hợp lệ trên các adapter tự kiểm tra body (Sora và Wan)
400	`missing_model`	Thiếu `model`; do các adapter tự kiểm tra body trả về (Sora và Wan). Các đường khác từ chối yêu cầu thiếu model trước khi định tuyến, dưới dạng lỗi middleware
400	`invalid_seconds`	`duration` / `seconds` âm hoặc lớn hơn 3600
400	`invalid_size`	Mô hình không chấp nhận kích thước này, ví dụ kích thước Sora không được hỗ trợ
400	`model_price_error`	RouteAPI không thể tính giá mô hình; không có gì được gửi đi
400	`model_not_supported`	Mô hình được phân giải thành mô hình mà kênh không còn phục vụ, như Seedance 1.x
400	`task_not_exist`	Tác vụ gốc của remix không tồn tại hoặc thuộc tài khoản khác
400	`task_source_unavailable`	Kênh của tác vụ gốc trong remix đã bị xóa hoặc tắt, hoặc thiếu adapter tương ứng
403	`insufficient_user_quota` / `pre_consume_token_quota_failed`	Số dư tài khoản hoặc hạn mức của Key không đủ chi phí ước tính; không có gì được gửi đi
429	—	Năng lực upstream đã cạn; thông báo được thay bằng văn bản chung “hãy thử lại sau”
500	`build_request_failed`, `do_request_failed`, `invalid_response`	Không chuyển đổi được tác vụ, kết nối upstream thất bại, hoặc upstream không trả về ID tác vụ
500	`get_channel_failed`, `task_persistence_failed`, `gen_relay_info_failed`	RouteAPI không thể chọn kênh hoặc ghi lại tác vụ; không bị tính phí (khoản giữ trước được hoàn)
502	`upstream_task_id_missing`	Upstream đã nhận tác vụ nhưng không trả ID tác vụ; tác vụ bị đánh dấu thất bại để giải phóng khoản giữ trước
bất kỳ	`fail_to_fetch_task`	Upstream trả về trạng thái khác 200 cho yêu cầu gửi; mã trạng thái HTTP là của upstream

Các yêu cầu bị từ chối trước khi định tuyến — API Key thiếu hoặc không hợp lệ (401), giới hạn IP, nhóm không có quyền, mô hình nằm ngoài danh sách cho phép của Key (403), hoặc mô hình không có kênh khả dụng (503, mã model_not_found) — dùng body lỗi middleware chuẩn {"error": {"message": ..., "type": "error", "code": ...}}, không dùng cấu trúc tác vụ.

Các lỗi xảy ra sau khi gửi (kiểm duyệt nội dung, upstream hết thời gian, hủy) không hiện ra dưới dạng lỗi HTTP. Chúng xuất hiện là FAILURE trong bản ghi tác vụ kèm fail_reason, và khoản đã giữ trước được hoàn lại.

Lấy tác vụ video — thăm dò bản ghi, đọc trạng thái và tải kết quả.
Seedance, Hailuo, Wan — tham số và giới hạn riêng của từng mô hình.
Asset — tải lên hình ảnh, video và âm thanh tái sử dụng và tham chiếu bằng asset://.
Lỗi thường gặp — mã trạng thái dùng chung cho mọi endpoint mô hình.