Cách sử dụng Seedance API: khóa, yêu cầu, truy vấn tác vụ và tham chiếu

Để dùng Seedance API, hãy tạo một khóa API, gửi thân tác vụ video chính thức của ModelArk tới một endpoint, rồi truy vấn tác vụ được trả về cho tới khi URL video sẵn sàng. Các bước tương tự áp dụng cho Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini và Seedance 2.5; chỉ giá trị model và một vài giới hạn riêng của từng mô hình thay đổi.

Hướng dẫn này đi qua từng bước với code chạy được, rồi chỉ cách thêm tham chiếu, chỉnh sửa clip bằng Seedance 2.5 và giao việc cho một coding agent.

Cần chuẩn bị gì trước yêu cầu đầu tiên?

1. Một khóa API. Tạo khóa trên trang khóa API và giữ nó trên máy chủ của bạn. Đừng bao giờ đặt nó trong code chạy trên trình duyệt.
2. Tín dụng. Nạp số dư trên trang thanh toán. Tín dụng không bao giờ hết hạn, và tác vụ thất bại không bị tính phí.
3. Một ID mô hình. Chọn một ID trong bảng bên dưới.

Chưa biết chọn mô hình nào? Hướng dẫn so sánh Seedance 2.0, Fast và Mini và hướng dẫn so sánh Seedance 2.5 và 2.0 so sánh các mô hình này.

export SEEDROUTER_API_KEY="your-key"

Gửi yêu cầu Seedance thế nào?

Gửi POST tác vụ tới /v1/contents/generations/tasks. Thân yêu cầu chính là yêu cầu "create a video generation task" (tạo tác vụ tạo video) chính thức của ModelArk:

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
    "resolution": "720p",
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": true
  }'

Phản hồi là một ID tác vụ, không phải một video:

{"id": "task_..."}

Nếu bạn đang gọi ModelArk, chỉ cần đổi base URL thành https://api.seedrouter.ai/v1 và đổi khóa API. Các trường không xác định bị từ chối trước khi có bất kỳ khoản phí nào, và một thiết lập mà mô hình không hỗ trợ cũng vậy, chẳng hạn 1080p trên Fast hoặc Mini.

Lấy video bằng cách nào?

Truy vấn tác vụ mỗi 10 đến 20 giây cho tới khi status là succeeded, failed hoặc expired. Một clip 5 giây 720p thường mất hai đến ba phút. Bằng Python:

import os
import time
import requests

API = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}

response = requests.post(
    f"{API}/contents/generations/tasks",
    headers=headers,
    json={
        "model": "dreamina-seedance-2-0",
        "content": [{"type": "text", "text": "A red paper boat drifts across a calm pond at sunrise, slow dolly-in"}],
        "resolution": "720p",
        "ratio": "16:9",
        "duration": 5,
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

deadline = time.monotonic() + 1800
while time.monotonic() < deadline:
    result = requests.get(f"{API}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    result.raise_for_status()
    task = result.json()
    if task["status"] == "succeeded":
        print(task["content"]["video_url"])
        break
    if task["status"] in ("failed", "expired"):
        raise RuntimeError(task["error"]["message"])
    time.sleep(15)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Tác vụ thành công có video trong content.video_url, số token video bị tính phí trong usage.completion_tokens, và các thiết lập thực tế đã được dùng để dựng, bao gồm cả seed mà mô hình đã chọn. Video được lưu trên kho lưu trữ của chúng tôi; hãy tải về kho lưu trữ của riêng bạn nếu cần dùng lâu dài.

Hết thời gian chờ khi truy vấn không có nghĩa là video đã thất bại. Hãy giữ ID tác vụ và kiểm tra lại; gửi một tác vụ mới đồng nghĩa với trả tiền cho video thứ hai. Không có callback URL, nên truy vấn là cách để lấy kết quả, và tác vụ đã gửi thì không thể hủy.

Thêm ảnh, video và âm thanh thế nào?

Thêm các mục vào content, mỗi mục có một URL công khai và một role:

curl https://api.seedrouter.ai/v1/contents/generations/tasks \
  -H "Authorization: Bearer $SEEDROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0",
    "content": [
      {"type": "text", "text": "The character from the image walks through the market in the video, same camera move"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "video_url", "video_url": {"url": "https://example.com/market.mp4"}, "role": "reference_video"}
    ],
    "ratio": "adaptive",
    "duration": 8
  }'

Seedance 2.0 cùng các phiên bản Fast và Mini nhận tối đa 9 ảnh tham chiếu, 3 video và 3 bản âm thanh; Seedance 2.5 nhận tối đa 30, 10 và 10. Media phải là URL: không chấp nhận base64 và tải tệp lên. Mô hình không hỗ trợ ảnh và video tham chiếu có khuôn mặt người thật. Media được kiểm tra khi tác vụ bắt đầu, và một tệp vi phạm giới hạn sẽ khiến tác vụ thất bại trước khi tạo bất cứ thứ gì, không bị tính phí.

Chỉnh sửa hoặc kéo dài clip bằng Seedance 2.5 thế nào?

Gửi clip dưới dạng reference_video và đặt omni_reference_task_type:

{
  "model": "dreamina-seedance-2-5",
  "content": [
    {"type": "text", "text": "Change the jacket to red. Keep everything else the same."},
    {"type": "video_url", "video_url": {"url": "https://example.com/clip.mp4"}, "role": "reference_video"}
  ],
  "omni_reference_task_type": "edit"
}

Dùng edit để thay đổi nội dung trong cảnh quay và extend để quay tiếp sau khung hình cuối của nó. Với edit, hãy để duration ở giá trị mặc định -1; với cả hai, hãy để ratio là adaptive. Số giây đầu vào được tính theo đơn giá tham chiếu, như hướng dẫn giá giải thích.

Làm sao để một coding agent dùng Seedance API?

Một coding agent như Claude Code, Codex hay Cursor có thể gọi API bằng một lệnh shell hoặc một script ngắn. SeedRouter không cung cấp MCP server, skill đóng gói sẵn hay node ComfyUI; prompt này là toàn bộ phần tích hợp. Hãy export khóa trước, rồi dán vào:

Use the SeedRouter API to generate a Seedance video for me.

Security: read SEEDROUTER_API_KEY from my local environment. Never ask me to paste it and never print it.

Goal: [subject, action, camera move, lighting, what the clip is for]
Model: [dreamina-seedance-2-0 | dreamina-seedance-2-0-fast | dreamina-seedance-2-0-mini | dreamina-seedance-2-5]
Resolution: [480p | 720p | 1080p | 4k]    Ratio: [16:9 | 9:16 | 1:1 | adaptive]    Duration: [seconds]
References: [public image, video or audio URLs with their roles, or none]

Send POST https://api.seedrouter.ai/v1/contents/generations/tasks with
{"model": "...",
 "content": [{"type": "text", "text": "..."}],
 "resolution": "...", "ratio": "...", "duration": 5}
Media goes in content as image_url, video_url or audio_url items with a role,
never base64. Do not add fields that are not in the API reference.

Before sending, show me the request body and wait for my approval: each
task is charged. Then poll GET https://api.seedrouter.ai/v1/contents/generations/tasks/{id}
every 15 seconds until status is succeeded, failed or expired. If polling
times out, keep checking the same task; never resubmit. Save
content.video_url into ./videos/ and tell me the file path.

Bước phê duyệt rất quan trọng: agent tiêu số dư của bạn, nên nó không bao giờ được tự ý gửi tác vụ.

Câu hỏi thường gặp

Làm sao để lấy khóa Seedance API?

Đăng nhập, mở trang khóa API và tạo một khóa. Cùng một khóa dùng được cho mọi mô hình Seedance và các mô hình khác trên SeedRouter.

Tài liệu Seedance API ở đâu?

Tài liệu API Seedance 2.0 và Seedance 2.5 liệt kê mọi trường, giới hạn và lỗi, với ví dụ bằng cURL, Python, Node.js và Go, kèm một tệp OpenAPI và một phiên bản Markdown có thể sao chép.

Có thể tạo nhiều video cùng lúc không?

Gửi một tác vụ cho mỗi video và truy vấn các tác vụ song song. Mỗi tác vụ trả về một video và được tính phí riêng. Để liệt kê các tác vụ gần đây, gọi GET /v1/contents/generations/tasks với page_num, page_size và các bộ lọc như filter.status.

Cần xử lý những lỗi nào?

Mã 400 nghĩa là thân yêu cầu vi phạm một quy tắc, chẳng hạn một trường không xác định hoặc một độ phân giải không được hỗ trợ, và không có gì bị tính phí. Tác vụ kết thúc failed hoặc expired có kèm mã lỗi và thông báo lỗi, và cũng không bị tính phí. Hướng dẫn lỗi liệt kê mọi mã lỗi và khi nào nên thử lại.

Gửi yêu cầu đầu tiên

Hãy tạo khóa, nạp một khoản nhỏ và chạy ví dụ Python ở trên, hoặc thử cùng yêu cầu đó mà không cần code trong playground Seedance 2.0. Với clip dài hơn và chỉnh sửa video, hãy đổi mô hình thành dreamina-seedance-2-5 và xem trang Seedance 2.5.