Seedance

Seedance là dòng mô hình tạo video của ByteDance, được cung cấp bởi các kênh Volcengine Ark. RouteAPI chuyển yêu cầu của bạn thành lời gọi /api/v3/contents/generations/tasks của Ark, nên mọi tác vụ đều đi theo cùng một luồng gửi, thăm dò và tải xuống như các mô hình video khác — xem Tạo tác vụ và Lấy tác vụ. Trang này mô tả những gì bộ chuyển đổi Seedance đọc, giới hạn theo từng mô hình, cách đọc bản ghi tác vụ Seedance và cách tính chi phí.

Tạo video là tác vụ bất đồng bộ: gửi yêu cầu, giữ task_id, thăm dò mỗi 10–15 giây, rồi tải xuống khi trạng thái là SUCCESS. Một clip 4 giây ở 480p thường mất từ một đến năm phút; độ phân giải cao hơn và thời lượng dài hơn sẽ lâu hơn.

Mô hình

ID mô hình	Mô hình Ark	Độ phân giải	Thời lượng	Ghi chú
`seedance-2.5`	`doubao-seedance-2-5-260628`	480p / 720p / 1080p	4–30 giây	Xem trước bản nháp, chế độ tham chiếu/chỉnh sửa/mở rộng, đầu ra `mov`
`seedance-2.0`	`doubao-seedance-2-0-260128`	480p / 720p / 1080p / 4k	4–15 giây	Nguyên liệu tham chiếu hình ảnh, video và âm thanh
`seedance-2.0-fast`	`doubao-seedance-2-0-fast-260128`	480p / 720p	4–15 giây	Biến thể 2.0 nhanh hơn, rẻ hơn
`seedance-2.0-mini`	`doubao-seedance-2-0-mini-260615`	480p / 720p	4–15 giây	Biến thể 2.0 giá thấp

Gửi ID do GET /v1/models trả về. Kênh phục vụ các mô hình này ánh xạ ID đó sang tên mô hình Ark tương ứng ở cột thứ hai, đó là lý do bộ chuyển đổi chấp nhận cả hai cách đặt tên. Tài khoản của bạn dùng được mô hình nào và giá bao nhiêu do console RouteAPI quy định.

Cột độ phân giải và thời lượng là phạm vi ByteDance quy định cho từng mô hình. RouteAPI không kiểm tra các phạm vi này: kiểm tra thời lượng duy nhất ở phía chúng tôi là quy tắc chung rằng duration / seconds cấp cao nhất phải nằm trong 0–3600 (xem Giới hạn và lỗi). Mọi thứ còn lại do Ark thực thi — yêu cầu 30 giây trên mô hình 2.0, độ phân giải không được hỗ trợ hay quá nhiều clip tham chiếu đều được gửi đi, sau đó bị Ark từ chối và hiện ra dưới dạng fail_to_fetch_task kèm trạng thái và thông báo của Ark. RouteAPI cũng không điền giá trị mặc định cho resolution hoặc duration bị thiếu; Ark tự áp dụng mặc định của nó. Ước tính chi phí trong trường hợp đó dùng 1080p và 5 giây, nên số tiền tạm giữ chỉ là ước tính, không phải mặc định của Ark.

Seedance 1.x (doubao-seedance-1-0-*, doubao-seedance-1-5-*) không còn được cung cấp. Yêu cầu ánh xạ tới tên 1.x bị từ chối với 400 và mã model_not_supported sau bước ánh xạ mô hình nhưng trước khi tạm giữ hay gửi lên upstream.

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

Trường khung	Bộ chuyển đổi Seedance làm gì
`prompt`	Được thêm làm mục `text` cuối cùng, trừ khi `metadata.content` đã có mục text hoặc `content` là `draft_task` 2.5. Bắt buộc trong mọi yêu cầu
`images` / `image`	Mỗi ảnh thành một mục `image_url` không có `role`. Bị bỏ qua khi có `metadata.content`
`ratio`	Gửi làm `ratio` của Ark
`resolution`	Gửi làm `resolution` của Ark
`duration`	Gửi làm `duration` của Ark; `seconds` cấp cao nhất phân tích được thành số nguyên dương sẽ thay thế
`generate_audio`	Gửi làm `generate_audio`; `false` tường minh vẫn được chuyển tiếp
`metadata`	Được giải mã vào cấu trúc có kiểu; giá trị của nó thắng các trường cấp cao nhất cùng tên

size, input_reference và mode thuộc khung chung nhưng bộ chuyển đổi Seedance không đọc chúng: hãy dùng resolution / ratio, và images hoặc content.

Kiểu của metadata được kiểm tra trước khi gửi: sai kiểu (content là object, image_url là chuỗi thô, duration: "abc") trả 400 và không bị tính phí. Thông báo bắt đầu bằng unmarshal metadata failed. Các giá trị số và boolean trong metadata cũng nhận dạng chuỗi ("duration": "6", "watermark": "false"); các trường vô hướng ở cấp cao nhất phải dùng đúng kiểu JSON.

Tham số cấp cao nhất

Các trường này được đọc ở cấp cao nhất của body, nên cùng cấu trúc gửi tới nhà cung cấp khác dùng được mà không cần bọc trong metadata:

Trường	Kiểu	Mô tả
`ratio`	string	Tỷ lệ khung hình: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9` hoặc `adaptive`
`resolution`	string	`480p`, `720p`, `1080p` hoặc `4k`, tùy mô hình
`duration`	integer	Thời lượng tính bằng giây. `0` nghĩa là “chưa đặt” và không được gửi; nếu cần chuyển tiếp số 0 tường minh, hãy dùng `metadata`
`generate_audio`	boolean	Tạo nhạc nền; `false` được chuyển tiếp tường minh
`seconds`	string	Dạng chuỗi cũ của thời lượng; khi phân tích được thành số nguyên dương, nó ghi đè cả `duration` và `metadata.duration`. Giá trị không phải số sẽ bị bỏ qua

Tham số metadata

Trường	Kiểu	Mô tả
`content`	array	Nguyên liệu đầu vào; thay thế `images`. Xem metadata.content
`ratio`, `resolution`, `duration`, `generate_audio`	như cấp cao nhất	Ưu tiên hơn giá trị cấp cao nhất. `seconds` dương vẫn thắng thời lượng cuối
`seed`	integer	Seed ngẫu nhiên; `0` được chuyển tiếp như giá trị tường minh
`frames`	integer	Số khung hình. Khi được đặt, nó thay thế thời lượng trong ước tính chi phí và Ark cũng dùng nó thay cho thời lượng
`camera_fixed`	boolean	Giữ camera cố định
`watermark`	boolean	Hình mờ phía nhà cung cấp trên đầu ra. ByteDance ghi mặc định là `false`
`return_last_frame`	boolean	Trả thêm khung hình cuối dưới dạng ảnh
`service_tier`	string	Bậc dịch vụ của nhà cung cấp, ví dụ `default`. Truyền nguyên trạng
`execution_expires_after`	integer	Thời gian hết hạn tác vụ tính bằng giây. ByteDance ghi 3600–259200, mặc định 172800; Ark thực thi
`priority`	integer	Ưu tiên hàng đợi phía nhà cung cấp, 0–9, số lớn hơn chạy trước. Ark chỉ sắp xếp tác vụ trong tài khoản của bạn
`safety_identifier`	string	Mã định danh người dùng cuối của bạn, tối đa 64 ký tự. Chuyển tới Ark, nơi kiểm tra độ dài
`draft`	boolean	Xem trước bản nháp Seedance 2.5 — xem Xem trước bản nháp
`output_format`	string	Định dạng chứa đầu ra, chuyển nguyên trạng. Seedance 2.5 nhận `mp4` (mặc định) hoặc `mov`
`omni_reference_task_type`	string	Chế độ tham chiếu Seedance 2.5, chuyển nguyên trạng: `auto`, `reference`, `edit` hoặc `extend`

callback_url không được chuyển tiếp và không có callback nào được gửi — hãy thăm dò kết quả. tools cũng bị bỏ; tìm kiếm web trên upstream không khả dụng qua API này. Các khóa không nhận diện được, kể cả hai khóa này, không gây lỗi mà bị bỏ qua. metadata.model không được đọc: model trong body luôn là tên mô hình upstream của kênh.

metadata.content

content là mảng có thứ tự các mục đầu vào. Mỗi mục có type, trường payload tương ứng và role tùy chọn:

`type`	Payload	Giá trị `role`
`text`	`text`	—
`image_url`	`image_url.url`	`first_frame`, `last_frame`, `reference_image`
`video_url`	`video_url.url`	`reference_video`
`audio_url`	`audio_url.url`	`reference_audio`
`draft_task`	`draft_task.id`	—

RouteAPI kiểm tra hình dạng của mục (kiểu payload sai trả 400) nhưng không kiểm tra tên role; role lạ vẫn được chuyển tiếp và Ark quyết định có từ chối hay không. URL có thể là liên kết http(s) công khai, URI data: cho hình ảnh và âm thanh, hoặc tham chiếu asset://<asset_id> — xem Asset để tải nguyên liệu lên và cho hình ảnh người thật, vốn phải đến từ một nhóm asset đã xác minh.

Các quy tắc đến từ quá trình chuyển đổi:

Nếu có content, nó được dùng nguyên trạng; images cấp cao nhất bị bỏ qua chứ không được hợp nhất. Mảng content rỗng được coi như không có, nên images cấp cao nhất vẫn có hiệu lực.
Nếu content không có mục text, prompt cấp cao nhất được thêm làm mục văn bản cuối cùng. Ngoại lệ duy nhất là yêu cầu 2.5 có content là draft_task: không thêm prompt, nhưng prompt vẫn phải có trong body.
Tham chiếu nguyên liệu bằng số thứ tự trong prompt (“image 1”, “video 1”), đánh số theo từng loại theo thứ tự trong content.
Khung đầu, khung đầu và cuối, và nguyên liệu đa tham chiếu là ba chế độ khác nhau. Đừng trộn chúng trừ khi bạn đã kiểm tra mô hình chấp nhận tổ hợp đó.

Các giới hạn tham chiếu dưới đây do Ark thực thi, không phải RouteAPI kiểm tra: yêu cầu vượt giới hạn vẫn được gửi đi và bị upstream từ chối.

Mục	Seedance 2.5	Dòng 2.0
Ảnh tham chiếu	1–30	1–9
Video tham chiếu	Tối đa 10 clip, tổng ≤30 giây	Tối đa 3 clip, tổng ≤15 giây
Âm thanh tham chiếu	Tối đa 10 clip, tổng ≤30 giây	Tối đa 3 clip, tổng ≤15 giây, và phải đi kèm ảnh hoặc video
Một ảnh	Dưới 30 MB, mỗi cạnh 300–6000 px	Như trên
Một video	mp4 / mov, dưới 200 MB	Như trên
Một âm thanh	wav / mp3, dưới 15 MB	Như trên

Seedance 2.x từ chối ảnh và video tham chiếu chứa khuôn mặt người thật. Để dùng chân dung người thật, trước tiên hãy hoàn tất xác minh người thật, rồi tham chiếu nguyên liệu đã xác minh bằng asset:// — Asset mô tả phiên xác minh, nhóm đã xác minh và các quy tắc của yêu cầu.

Văn bản thành video

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": "A paper boat drifting down a rain-soaked street, cinematic lighting",
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": false
  }'

Khung đầu và khung đầu + khung cuối

Một ảnh trong images trở thành mục ảnh không có role, mà Seedance coi là khung đầu:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "The camera slowly pushes in as the person looks up and smiles",
    "images": ["https://cdn.example.com/first.jpg"],
    "ratio": "adaptive",
    "resolution": "720p",
    "duration": 5
  }'

Để điều khiển tường minh khung đầu/khung cuối, hãy dùng content và đặt prompt bên trong:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "The bud slowly opens into a full bloom",
    "metadata": {
      "content": [
        { "type": "text", "text": "The bud slowly opens into a full bloom" },
        { "type": "image_url", "image_url": { "url": "https://cdn.example.com/bud.jpg" }, "role": "first_frame" },
        { "type": "image_url", "image_url": { "url": "https://cdn.example.com/flower.jpg" }, "role": "last_frame" }
      ],
      "ratio": "adaptive",
      "resolution": "720p",
      "duration": 5
    }
  }'

Tham chiếu đa phương thức

Ảnh, video và âm thanh tham chiếu được trộn trong một mảng content với các role reference_*. Đánh số nguyên liệu theo từng loại, theo thứ tự trong content, và tham chiếu chúng như vậy trong prompt:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.0",
    "prompt": "The person in image 1 dances following the moves in video 1, with audio 1 as background music",
    "metadata": {
      "content": [
        { "type": "text", "text": "The person in image 1 dances following the moves in video 1, with audio 1 as background music" },
        { "type": "image_url", "image_url": { "url": "https://cdn.example.com/person.jpg" }, "role": "reference_image" },
        { "type": "video_url", "video_url": { "url": "https://cdn.example.com/dance.mp4" }, "role": "reference_video" },
        { "type": "audio_url", "audio_url": { "url": "https://cdn.example.com/bgm.mp3" }, "role": "reference_audio" }
      ],
      "ratio": "16:9",
      "resolution": "720p",
      "duration": 10
    }
  }'

Yêu cầu có đầu vào video được tính theo giá đầu vào video của mô hình — xem Tính phí. Số lượng, độ dài và định dạng nguyên liệu tham chiếu do Ark thực thi; xem bảng giới hạn trong metadata.content.

Chế độ riêng của nhà cung cấp (Seedance 2.5)

Seedance 2.5 thêm bộ chọn chế độ và lựa chọn định dạng chứa. Cả hai đều được chuyển nguyên trạng cho mọi mô hình Seedance, và Ark quyết định có chấp nhận hay không:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "Continue the scene as the camera pulls back over the harbour",
    "metadata": {
      "omni_reference_task_type": "extend",
      "output_format": "mov",
      "content": [
        { "type": "text", "text": "Continue the scene as the camera pulls back over the harbour" },
        { "type": "video_url", "video_url": { "url": "https://cdn.example.com/scene.mp4" }, "role": "reference_video" }
      ],
      "ratio": "16:9",
      "duration": 8
    }
  }'

omni_reference_task_type nhận auto (mặc định), reference, edit hoặc extend. Tổ hợp đầu vào mà mỗi chế độ mong đợi thuộc hợp đồng của ByteDance; RouteAPI chỉ chuyển tiếp giá trị.

Xem trước bản nháp

Bản nháp là bản xem trước chi phí thấp. Tạo video cuối từ nó là tác vụ thứ hai, được tính phí riêng.

Gửi yêu cầu có "metadata": { "draft": true, ... } và chờ SUCCESS.
Đọc ID tác vụ upstream từ bản ghi tác vụ: GET /v1/video/generations/{task_id} → data.data.id.
Gửi một tác vụ mới có content là một draft_task duy nhất.

Bước 1:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "An astronaut walks slowly on the moon",
    "metadata": { "draft": true, "duration": 5, "ratio": "16:9" }
  }'

Bước 2, sau khi tác vụ bản nháp báo SUCCESS. data.data.id là ID tác vụ Ark và không phải data.task_id bên ngoài:

curl -s https://api.routeapi.ai/v1/video/generations/task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV \
  -H "Authorization: Bearer $ROUTEAPI_KEY" | jq -r .data.data.id

Bước 3:

curl https://api.routeapi.ai/v1/video/generations \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "x",
    "metadata": {
      "content": [ { "type": "draft_task", "draft_task": { "id": "cgt-xxxxxxxx" } } ],
      "resolution": "1080p",
      "duration": 5
    }
  }'

prompt vẫn bắt buộc; trong dạng này nó không được gửi làm văn bản, nên bất kỳ chuỗi giữ chỗ không rỗng nào cũng được. Phần tiếp nối draft_task không có duration tường minh sẽ được tạm giữ như thể chạy tới mức trần thời lượng tự động của mô hình (30 giây trên 2.5, 15 giây trên 2.0) rồi quyết toán theo mức dùng thực tế.

ID bản nháp thuộc về Ark. ByteDance ghi thời hạn 7 ngày; RouteAPI không kiểm tra, nên ID bản nháp hết hạn sẽ lỗi ở upstream.

Truy vấn tác vụ

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

{
  "code": "success",
  "message": "",
  "data": {
    "id": 4512,
    "created_at": 1792048450,
    "updated_at": 1792048569,
    "task_id": "task_G2RdWGt4t1nck5fYqTjwREKJo8Ze4RAV",
    "platform": "54",
    "user_id": 1024,
    "group": "default",
    "channel_id": 18,
    "quota": 108900,
    "action": "generate",
    "status": "SUCCESS",
    "progress": "100%",
    "fail_reason": "",
    "result_url": "https://ark-content.example/xxxx.mp4",
    "submit_time": 1792048458,
    "start_time": 1792048461,
    "finish_time": 1792048569,
    "properties": {
      "input": "{\"model\":\"doubao-seedance-2-0-fast-260128\",\"content\":[{\"type\":\"text\",\"text\":\"An orange cat stretching on a windowsill at sunrise\"}],\"generate_audio\":false,\"resolution\":\"720p\",\"ratio\":\"16:9\",\"duration\":5}",
      "origin_model_name": "seedance-2.0-fast",
      "upstream_model_name": "doubao-seedance-2-0-fast-260128"
    },
    "data": {
      "id": "cgt-20261023100444-9kz46",
      "model": "doubao-seedance-2-0-fast-260128",
      "status": "succeeded",
      "content": { "video_url": "https://ark-content.example/xxxx.mp4" },
      "seed": 8202,
      "resolution": "720p",
      "duration": 5,
      "ratio": "16:9",
      "framespersecond": 24,
      "usage": { "completion_tokens": 108900, "total_tokens": 108900 },
      "created_at": 1792048458,
      "updated_at": 1792048569
    }
  }
}

Các trường bên ngoài do RouteAPI tạo, và Lấy tác vụ mô tả đầy đủ. Với Seedance, hãy đọc data.status, data.progress, data.result_url, data.fail_reason và data.quota — quota là số tiền đã tính đến hiện tại, sau khi tác vụ thành công là số tiền đã quyết toán. data.properties.input là bản chụp JSON chính xác mà RouteAPI đã gửi tới Ark (URL media dài hơn 512 byte được thay bằng [omitted, N bytes]), cách nhanh nhất để xác nhận yêu cầu thực sự đi ra với độ phân giải bạn muốn. data.platform là loại kênh: 54 với kênh video Doubao, 45 với kênh Volcengine.

data.data là body tác vụ của chính Ark, được lưu nguyên trạng, và có thể chưa đầy đủ trước khi tác vụ kết thúc. Nếu upstream của kênh trả qua lớp bọc gateway ({"code": 200, "data": {...}}), các trường bên dưới nằm sâu thêm một cấp, trong data.data.data — hãy đánh giá theo data.status, không phải theo sự có mặt của một trường. Các trường đáng đọc:

Trường	Ý nghĩa
`data.data.id`	ID tác vụ Ark, khác với `data.task_id` bên ngoài. Dùng cho bước tạo cuối từ bản nháp 2.5
`data.data.content.video_url`	URL video Ark trả về; cùng giá trị với `data.result_url` bên ngoài
`data.data.content.last_frame_url`	Ảnh khung cuối. Chỉ có khi bật `return_last_frame`. RouteAPI lưu nguyên payload này và chỉ phân tích `content.video_url` từ đó
`data.data.duration` / `resolution` / `ratio` / `framespersecond` / `seed`	Tham số sinh thực tế
`data.data.usage.completion_tokens` / `total_tokens`	Số token Ark đo được; `total_tokens` là lượng dùng để quyết toán
`data.data.error`	Mã và thông báo lỗi của Ark khi thất bại

Trạng thái của Ark ánh xạ vào bản ghi tác vụ như sau; trạng thái RouteAPI không nhận diện được coi là vẫn đang chạy:

`status` của Ark	Trạng thái bản ghi tác vụ	Tiến độ
`pending`, `queued`	`QUEUED`	`10%`
`processing`, `running`	`IN_PROGRESS`	`50%`
`succeeded`	`SUCCESS`	`100%`
`failed`, `expired`, `cancelled`	`FAILURE`	`100%`
khác	`IN_PROGRESS`	`30%`

Nếu Ark báo succeeded trước khi có video_url, RouteAPI giữ tác vụ ở IN_PROGRESS và thăm dò lại thay vì quyết toán một tác vụ không có kết quả. Khi FAILURE, fail_reason là thông báo lỗi của Ark, nếu thiếu thì là task failed; tác vụ expired hoặc cancelled không có object lỗi báo task expired hoặc task cancelled. Nếu thời gian chờ tác vụ của chính RouteAPI (mặc định 24 giờ) kích hoạt trước, trạng thái cũng là FAILURE kèm thông báo của nền tảng, và cả hai trường hợp đều hoàn lại số tiền tạm giữ.

Tải video xuống

data.result_url là URL của chính Ark, và Ark làm nó hết hạn theo lịch của mình (tài liệu ByteDance ghi khoảng 24 giờ) — hãy tải xuống sớm. Endpoint nội dung của RouteAPI lấy lại URL đã lưu tại thời điểm gọi, giúp bạn khỏi phải tự theo dõi những liên kết sắp hết hạn nhưng không thể làm sống lại một liên kết đã hết hạn:

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

Endpoint nội dung 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, task_id không tồn tại hoặc của người khác trả 404, và lỗi khi lấy tệp từ Ark trả 502. Lỗi của nó dùng dạng {"error": {"message": "...", "type": "..."}} không có trường code. Nếu bật return_last_frame, data.data.content.last_frame_url cũng hết hạn theo lịch của Ark — hãy tải cùng lúc.

Tính phí

Mô hình Seedance tính phí theo token, không phải theo yêu cầu hay theo giây. Giá trên console là giá mỗi triệu token đầu ra cho một bậc độ phân giải; yêu cầu có đầu vào video được tính theo giá đầu vào video của mô hình.

Khi gửi, RouteAPI ước tính token đầu ra từ độ phân giải và số khung hình được yêu cầu:

frames  = 24 × duration + 1        (frames replaces duration when metadata.frames is set)
tokens  = pixels × frames / 1024
pixels  = 480p: 864×496, 720p: 1280×720, 1080p: 1920×1080, 4k: 3840×2160

Thời lượng mặc định là 5 giây khi bị bỏ trống, và là mức trần thời lượng tự động của mô hình (30 giây trên 2.5, 15 giây trên 2.0) khi content là draft_task không có thời lượng tường minh. Độ phân giải bị bỏ trống hoặc không nhận diện được sẽ ước tính theo 1080p. Thời lượng tự động của ByteDance (-1) bị kiểm tra 0–3600 từ chối ở cấp cao nhất; nếu gửi dưới dạng chuỗi "-1" trong metadata, nó được chuyển tiếp và ước tính dùng cùng mức trần tự động. Ước tính được nhân với hệ số mô hình, hệ số nhóm và hệ số đầu vào video, và số tiền đó được tạm giữ. Với mô hình tính theo hệ số thay vì giá cố định, ước tính được so với khoản trừ trước thông thường và số lớn hơn được tạm giữ. Quyết toán theo token khi hoàn tất chỉ chạy khi mô hình có cấu hình hệ số; nếu mô hình không có hệ số, khoản tạm giữ trở thành khoản thu cuối cùng (và nếu mô hình không có cả hệ số lẫn giá cố định, yêu cầu sẽ bị từ chối trừ khi tài khoản của bạn cho phép mô hình chưa cấu hình hệ số).

Yêu cầu	Tạm giữ khi gửi	Khi thành công
Có `duration`	token ước tính × giá	`usage.total_tokens` của Ark × giá, phần chênh được trừ thêm hoặc hoàn lại
Không có `duration`	ước tính theo 5 giây	cùng cách quyết toán
Có `metadata.frames`	ước tính dùng số khung hình	cùng cách quyết toán
`draft_task` không có `duration`	ước tính theo 30 giây / 15 giây	cùng cách quyết toán
Có giá cố định theo tác vụ	giá cố định	không đổi; không quyết toán theo token
`SUCCESS` nhưng không có `usage`	—	giữ nguyên khoản tạm giữ
`FAILURE`, `expired`, `cancelled`	—	hoàn lại khoản tạm giữ
`400`	không tạm giữ	không tính phí

Giá mỗi token phụ thuộc vào bậc độ phân giải đầu ra, việc yêu cầu có đầu vào video hay không, và — trên các mô hình có bảng giá định nghĩa chiều này — việc có tạo âm thanh hay không. Khi bảng giá của mô hình được dùng và hệ số tính ra không phải 1.0, header X-New-Api-Other-Ratios của phản hồi gửi sẽ mang nó dưới dạng mục video_input. Bảng giá dự phòng tích hợp đặt cho mô hình 2.0 các bậc base (480p / 720p), 1080p và 4k cùng giá đầu vào video cho từng bậc; biến thể fast chỉ có bậc base và hệ số đầu vào video 22/37. seedance-2.5 và seedance-2.0-mini không có bảng giá tích hợp, các bậc của chúng đến từ cấu hình console. Kênh cũng có thể ghi đè hệ số bằng bảng VideoPrice khóa theo ID mô hình bạn yêu cầu. Giá và bậc hiển thị trên console là chuẩn.

Ví dụ tính toán (giá đều là giả định; dùng console cho giá thật). Giả sử seedance-2.0-fast có giá $2 mỗi 1 triệu token đầu ra ở 720p và hệ số nhóm là 1:

Gửi ở 720p, duration: 5. Ước tính: 1280 × 720 = 921.600 pixel, 24 × 5 + 1 = 121 khung, 921.600 × 121 / 1024 = 108.900 token, tạm giữ $0.2178.
Ark báo usage.total_tokens: 105000, nên số tiền quyết toán là $0.21 và $0.0078 được hoàn lại.
Nếu cùng yêu cầu có thêm mục reference_video, bảng giá tích hợp của biến thể fast sẽ áp hệ số đầu vào video 22/37 ≈ 0.5946 cho cả ước tính lẫn quyết toán: tạm giữ ≈ $0.1295, quyết toán ≈ $0.1249.

Yêu cầu mà số dư hoặc hạn mức của Key không đủ cho khoản tạm giữ sẽ bị từ chối trước khi gửi lên upstream: 403 insufficient_user_quota với ví, 403 pre_consume_token_quota_failed với hạn mức Key.

Giới hạn và lỗi

Trạng thái	Mã	Ý nghĩa
400	`invalid_request`	`prompt` thiếu hoặc rỗng, JSON sai định dạng, hoặc trường metadata sai kiểu
400	`invalid_seconds`	`duration` / `seconds` cấp cao nhất, hoặc `metadata.duration` dạng số, âm hoặc lớn hơn 3600
400	`model_not_supported`	Yêu cầu ánh xạ tới mô hình Seedance 1.x đã ngừng cung cấp
400	`task_not_exist`	`task_id` không tồn tại hoặc thuộc tài khoản khác
403	`insufficient_user_quota`, `pre_consume_token_quota_failed`	Số dư ví hoặc hạn mức Key không đủ cho khoản tạm giữ
429	—	Công suất upstream cạn; thông báo đượ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, không tới được upstream, hoặc Ark không trả ID tác vụ
500	`get_channel_failed`	Chọn kênh thất bại ở phía relay (ví dụ bản ghi kênh biến mất giữa chừng)
503	`get_channel_failed`	Kênh gặp lỗi nghiêm trọng về thông tin xác thực hoặc thanh toán ở upstream; chi tiết bị ẩn
trạng thái upstream	`fail_to_fetch_task`	Ark từ chối gửi; trạng thái HTTP và thông báo là của Ark

Các thông báo 400 thường gặp, đúng như trả về:

`message`	Nguyên nhân
`prompt is required`	`prompt` thiếu, rỗng hoặc chỉ có khoảng trắng
`seconds must be between 1 and 3600`	`duration` / `seconds` cấp cao nhất, hoặc `metadata.duration` dạng số, âm hoặc quá lớn
`unmarshal metadata failed: ...`	Một trường `metadata` sai kiểu; phần sau của thông báo nêu tên trường đó
`model <id> is not supported by this channel`	Tên mô hình gốc hoặc upstream khớp với Seedance 1.x đã ngừng cung cấp
`task_not_exist`	ID tác vụ không tồn tại, hoặc thuộc tài khoản khác

Các lỗi sau khi gửi (kiểm duyệt nội dung, nhà cung cấp quá thời gian, hủy) không hiện ra dưới dạng lỗi HTTP. Chúng hiện trên bản ghi tác vụ là FAILURE kèm fail_reason, và khoản tạm giữ được hoàn lại. expired và cancelled cũng được báo theo cách này.

Khác biệt so với API Volcengine Ark

Endpoint khác. RouteAPI không cung cấp /api/v3/contents/generations/tasks, nên trỏ SDK Volcengine vào base URL của chúng tôi sẽ không dùng được.
Tham số riêng của Ark đặt trong metadata; các trường chung (prompt, images, ratio, resolution, duration, generate_audio) cũng có thể gửi ở cấp cao nhất và được ánh xạ hộ bạn.
task_id trả về là ID của RouteAPI, không phải của Ark. ID của Ark nằm ở data.data.id trên bản ghi tác vụ.
Bạn gửi ID mô hình trong danh mục; kênh ánh xạ nó sang tên mô hình Ark, nên bạn không bao giờ địa chỉ hóa trực tiếp endpoint ID của Ark (ep-...).
Không hỗ trợ liệt kê tác vụ, hủy tác vụ, callback và tìm kiếm web; callback_url và tools bị bỏ.
Tính phí theo token dựa trên bảng giá của console, không theo cách tính phí riêng của Ark.

Script hoàn chỉnh

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":"seedance-2.0-fast","prompt":"An orange cat stretching on a windowsill at sunrise","duration":5,"resolution":"720p","ratio":"16:9","generate_audio":false}' \
  | 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)
      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

Vòng lặp chờ 15 phút; tăng số lần cho tác vụ dài hoặc độ phân giải cao.