Định dạng video OpenAI

POST /v1/videos và GET /v1/videos/{task_id} là phương ngữ video OpenAI của cùng API tác vụ bất đồng bộ được mô tả tại Tạo tác vụ video và Lấy tác vụ video. Body gửi dùng cùng các trường; khác biệt nằm ở phản hồi: cả phản hồi gửi và GET đều trả về đối tượng video OpenAI thay vì bản ghi tác vụ. Đây là định dạng các mô hình Sora dùng, và cũng là định dạng mà client video của OpenAI SDK mong đợi.

Endpoint

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

Gửi

curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2",
    "prompt": "A calico cat playing a piano on stage",
    "size": "1280x720",
    "seconds": "4"
  }'

Các trường yêu cầu là những trường ở Tạo tác vụ video: model, prompt, seconds / duration, size, input_reference, images và metadata. input_reference được các mô hình hỗ trợ ảnh tham chiếu sử dụng. multipart/form-data cũng được chấp nhận, nên có thể tải tệp trực tiếp:

curl https://api.routeapi.ai/v1/videos \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -F "model=sora-2" \
  -F "prompt=A calico cat playing a piano on stage" \
  -F "size=1280x720" \
  -F "seconds=4" \
  -F "input_reference=@cat.jpg"

Phản hồi gửi

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "sora-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1792048458
}

id là ID tác vụ RouteAPI. task_id là bí danh tương thích và có thể không còn xuất hiện trong phản hồi sau này; hãy đọc id. Luôn dùng id này để thăm dò và tải về; các ID xuất hiện trong payload upstream đã lưu không phải giá trị bạn dùng.

Phản hồi gửi cũng mang 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 yêu cầu Sora.

Lấy đối tượng video

GET /v1/videos/{task_id}

curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

{
  "id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
  "object": "video",
  "model": "seedance-2.0",
  "status": "completed",
  "progress": 100,
  "created_at": 1792048458,
  "completed_at": 1792048569,
  "metadata": { "url": "https://...mp4" }
}

Trường	Mô tả
`id`	ID tác vụ RouteAPI
`object`	Luôn là `"video"`
`model`	Mô hình đã chạy tác vụ
`status`	`queued`, `in_progress`, `completed` hoặc `failed`
`progress`	Số nguyên 0–100
`created_at` / `completed_at`	Giây Unix. Một số adapter điền `completed_at` bằng thời điểm cập nhật cuối của dòng, nên hãy xác định hoàn tất qua `status`, không dựa vào trường này
`expires_at`, `size`, `seconds`, `remixed_from_video_id`	Chỉ có khi nhà cung cấp trả về
`metadata.url`	URL video cho các nhà cung cấp báo URL qua đối tượng video. Dùng `/v1/videos/{task_id}/content` nếu muốn lấy byte bất kể nhà cung cấp
`error.code` / `error.message`	Được đặt khi tác vụ thất bại, ví dụ `expired` hoặc `cancelled` với Seedance

Các trường riêng của payload upstream (như expires_at hay size) chỉ xuất hiện khi nhà cung cấp trả về; tập ở trên là những gì RouteAPI đảm bảo ánh xạ. Trên kênh Gemini và Vertex, trạng thái tác vụ được làm mới từ nhà cung cấp trước khi đối tượng này được dựng.

Tác vụ được giới hạn theo người dùng của API Key: id thuộc tài khoản khác được báo là task_not_exist, giống hệt endpoint bản ghi tác vụ.

Tải nội dung

GET /v1/videos/{task_id}/content

Trả về byte của video, truyền qua RouteAPI. Phản hồi mang Cache-Control: public, max-age=86400 và Content-Type của upstream. Đường dẫn chấp nhận API Key hoặc phiên console và chỉ phục vụ tác vụ do bên gọi sở hữu. Mã lỗi và ví dụ curl xem tại Tải video.

Remix

POST /v1/videos/{video_id}/remix

Tạo tác vụ mới từ video có sẵn. RouteAPI tìm video_id trong các tác vụ của bạn, suy ra mô hình từ đó, và ghim yêu cầu vào kênh đã tạo video gốc để kết quả giữ được tương thích.

curl https://api.routeapi.ai/v1/videos/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV/remix \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "The same cat, now wearing a tiny hat" }'

Remix có ý nghĩa với dòng Sora (sora-2, sora-2-pro), nơi yêu cầu được chuyển tới endpoint remix riêng của upstream và prompt là bắt buộc. Với các nền tảng khác, yêu cầu vẫn được chấp nhận, mô hình và kênh được phân giải từ tác vụ gốc, và tác vụ được adapter của mô hình đó dựng — nhưng upstream không bao giờ nhận chỉ dẫn remix, nên tác vụ mới chỉ là một lần tạo thông thường, không phải dẫn xuất từ video_id.

Remix kế thừa hệ số tính phí của tác vụ gốc khi adapter đã ghi lại, nên tác vụ mới được tính giá như tác vụ gốc thay vì theo giá trị mặc định.

Sora

Mô hình Sora dùng trực tiếp nhóm endpoint này; các tham số quan trọng là size và seconds.

Mô hình	Kích thước chấp nhận
`sora-2`	`720x1280`, `1280x720`
`sora-2-pro`	`720x1280`, `1280x720`, `1792x1024`, `1024x1792`

Kích thước không được hỗ trợ trả về 400 với mã invalid_size trước khi bất cứ khoản nào được giữ trước.
Giá trị mặc định là 720x1280 và 4 giây.
seconds (hoặc duration) được kiểm tra như mọi mô hình video khác: giá trị âm và giá trị lớn hơn 3600 bị từ chối với 400 invalid_seconds.
input_reference được chuyển tiếp như ảnh tham chiếu; cả gửi JSON lẫn multipart đều hoạt động.
Chi phí tính từ seconds và size: đầu ra 1792x1024 hoặc 1024x1792 tốn thêm hệ số kích thước (1.666667) trên mức giá theo giây. Các hệ số đã áp dụng được trả về trong X-New-Api-Other-Ratios.
Dòng này hỗ trợ remix.

Tính khả dụng và giá phụ thuộc tài khoản — hãy xác nhận mô hình xuất hiện trong GET /v1/models và xem trang chi tiết mô hình.

Lỗi

Sau khi định tuyến, cấu trúc lỗi tác vụ được áp dụng:

Trạng thái	Mã	Ý nghĩa
400	`invalid_request`	Thiếu hoặc để trống `prompt`, body sai định dạng, hoặc trường sai kiểu
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	`task_not_exist`	`video_id` trong 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 đã bị xóa hoặc tắt, hoặc thiếu adapter tương ứng
400	`asset_remix_conflict`	Remix tác vụ không dùng asset cố tham chiếu vật liệu `asset://`
429	—	Năng lực upstream đã cạn; thông báo được thay bằng nhắc thử lại chung
500	`build_request_failed`, `do_request_failed`	Không chuyển đổi được tác vụ hoặc kết nối upstream thất bại
500	`convert_to_openai_video_failed`	Dữ liệu tác vụ đã lưu không chuyển đổi được thành đối tượng video
501	`not_implemented`	`GET /v1/videos/{task_id}` trên nền tảng có adapter không hỗ trợ chuyển đổi video OpenAI
bất kỳ	`fail_to_fetch_task`	Upstream trả trạng thái khác 200 cho yêu cầu gửi; mã trạng thái HTTP là của upstream

Yêu cầu bị từ chối trước khi định tuyến dùng body chuẩn {"error": {"message": ..., "type": "error", "code": ...}} thay thế.

Tạo tác vụ video — khung yêu cầu dùng chung và lỗi ở bước gửi.
Lấy tác vụ video — phương ngữ bản ghi tác vụ, trạng thái và endpoint tải nội dung.
Seedance, Hailuo, Wan — tham số riêng của từng mô hình.