Как пользоваться Seedance API: ключ, запрос, опрос задачи и референсы

Чтобы пользоваться Seedance API, создайте API-ключ, отправьте официальное тело видеозадачи ModelArk на единую конечную точку и опрашивайте возвращённую задачу, пока не будет готов URL видео. Те же шаги работают для Seedance 2.0, Seedance 2.0 Fast, Seedance 2.0 Mini и Seedance 2.5; меняются только значение model и несколько лимитов, специфичных для модели.

В этой инструкции каждый шаг разобран на рабочем коде, а затем показано, как добавлять референсы, редактировать ролик с помощью Seedance 2.5 и поручить работу ИИ-агенту для программирования.

Что нужно перед первым запросом?

1. API-ключ. Создайте его на странице API-ключей и храните на своём сервере. Никогда не размещайте его в браузерном коде.
2. Кредиты. Пополните баланс на странице оплаты. Кредиты не сгорают, а неудачные задачи не оплачиваются.
3. ID модели. Выберите его в таблице ниже.

Не знаете, какую выбрать? Модели сравниваются в сравнении Seedance 2.0, Fast и Mini и в обзоре Seedance 2.5 и 2.0.

export SEEDROUTER_API_KEY="your-key"

Как отправить запрос к Seedance?

Отправьте задачу методом POST на /v1/contents/generations/tasks. Тело запроса — это официальный запрос ModelArk «create a video generation task» (создание задачи генерации видео):

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
  }'

В ответ приходит ID задачи, а не видео:

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

Если вы уже работаете с ModelArk, поменяйте только базовый URL на https://api.seedrouter.ai/v1 и API-ключ. Неизвестные поля отклоняются до какого-либо списания, как и настройки, которые модель не поддерживает, например 1080p на Fast или Mini.

Как получить видео?

Опрашивайте задачу каждые 10–20 секунд, пока status не станет succeeded, failed или expired. 5-секундный ролик в 720p обычно готовится две-три минуты. На 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}.")

В успешно завершённой задаче видео находится в content.video_url, тарифицированные видеотокены — в usage.completion_tokens, а также указаны фактически использованные при рендере настройки, включая seed, который выбрала модель. Видео хранится в нашем хранилище; если оно нужно вам надолго, скачайте его к себе.

Тайм-аут при опросе не означает, что видео не получилось. Сохраните ID задачи и проверьте её снова; отправка новой задачи означает оплату второго видео. URL обратного вызова нет, поэтому результат получают опросом, а отправленную задачу отменить нельзя.

Как добавить изображения, видео и аудио?

Добавьте элементы в content, каждый с публичным URL и 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 и её версии Fast и Mini принимают до 9 референсных изображений, 3 видео и 3 аудиодорожек; Seedance 2.5 — до 30, 10 и 10. Медиафайлы передаются только по URL: base64 и загрузка файлов не принимаются. Референсные изображения и видео с реальными человеческими лицами модель не поддерживает. Медиафайлы проверяются при запуске задачи, и файл, нарушающий лимит, приводит к сбою задачи до какой-либо генерации, без списания.

Как отредактировать или продлить ролик с помощью Seedance 2.5?

Отправьте ролик как reference_video и задайте 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"
}

Используйте edit, чтобы изменить содержимое видео, и extend, чтобы продолжить его после последнего кадра. Для edit оставьте duration со значением по умолчанию -1; в обоих случаях оставьте ratio равным adaptive. Входные секунды тарифицируются по референсному тарифу, как объясняется в руководстве по ценам.

Как поручить работу с Seedance API ИИ-агенту для программирования?

ИИ-агент для программирования, например Claude Code, Codex или Cursor, может вызывать API командой оболочки или коротким скриптом. SeedRouter не поставляет MCP-сервер, готовый skill или узел ComfyUI; этот промпт — вся интеграция. Сначала экспортируйте ключ, затем вставьте:

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.

Шаг с подтверждением важен: агент тратит ваш баланс, поэтому он никогда не должен отправлять задачу сам.

Часто задаваемые вопросы

Как получить API-ключ Seedance?

Войдите в аккаунт, откройте страницу API-ключей и создайте ключ. Один и тот же ключ работает для всех моделей Seedance и для остальных моделей в SeedRouter.

Где документация Seedance API?

В справочниках API Seedance 2.0 и Seedance 2.5 перечислены все поля, лимиты и ошибки, с примерами на cURL, Python, Node.js и Go, а также есть файл OpenAPI и версия в Markdown, которую можно скопировать.

Можно ли генерировать несколько видео одновременно?

Отправляйте по одной задаче на видео и опрашивайте задачи параллельно. Каждая задача возвращает одно видео и оплачивается отдельно. Чтобы получить список последних задач, вызовите GET /v1/contents/generations/tasks с page_num, page_size и фильтрами вроде filter.status.

Какие ошибки нужно обрабатывать?

400 означает, что тело запроса нарушило правило, например содержит неизвестное поле или неподдерживаемое разрешение, и ничего не списывается. Задача, завершившаяся со статусом failed или expired, содержит код ошибки и сообщение и тоже не оплачивается. В руководстве по ошибкам перечислены все коды и указано, когда повторять запрос.

Отправьте первый запрос

Создайте ключ, пополните баланс на небольшую сумму и запустите пример на Python выше или попробуйте тот же запрос без кода в playground Seedance 2.0. Для более длинных роликов и редактирования замените модель на dreamina-seedance-2-5 и загляните на страницу Seedance 2.5.