Doubao Seedance 2.0 Video API: генерация видео через задачи Volcengine Ark

Doubao Seedance 2.0 — семейство video generation моделей ByteDance. Практическая форма API асинхронная: создать generation task, сохранить task id, опрашивать статус до успеха, затем забрать video URL до истечения срока. Если вы используете TheRouter, безопасный подход — routing проверенных Seedance model IDs через media endpoints и явное тестирование provider-specific task fields.

Мы написали это руководство, потому что запросы по Seedance уже выглядят как implementation work: разработчики спрашивают не о существовании модели, а о том, какой endpoint вызвать, какой model id передать и где держать polling loop. Короткий ответ: используйте doubao/doubao-seedance-2-0 для финальных рендеров, doubao/doubao-seedance-2-0-fast для итераций, и проектируйте каждый запрос как retryable async workflow.

1. Меняйте три значения, а не три SDK. Замените api_key, base_url и model в существующем клиенте OpenAI. Код запроса и ответа оставьте неизменным.
2. Сопоставьте model ID явно. ID модели у целевого провайдера почти никогда не совпадает с OpenAI ID. Держите словарь { openai_id: target_id } вне бизнес-логики.
3. Проверьте формат streaming. SSE-чанки должны соответствовать контракту OpenAI: data: {...} + data: [DONE]. Прогоните один streaming вызов до продакшена.
4. Проверьте rate-limit заголовки. Некоторые провайдеры не возвращают x-ratelimit-*. Добавьте обёртку с безопасным дефолтом.
5. Оставьте путь отката. Раскатайте замену под feature flag, гоняйте оба endpoint в shadow-режиме 24 часа, затем переключайтесь.

Seedance 2.0 кратко

Страница ByteDance Seed описывает Seedance 2.0 как unified multimodal audio-video joint generation architecture с text, image, audio и video inputs. В документации Volcengine Ark есть отдельный раздел video generation API с create, query, list, cancel и delete task pages; create-task page обновлена 2026-06-25. Sources: ByteDance Seedance 2.0, Volcengine Ark create video generation task API, Volcengine Ark Seedance 2.0 tutorial. Retrieved 2026-06-26.

Когда выбирать Standard или Fast

Выбирайте standard Seedance 2.0, когда ролик близок к production: product hero shots, финальные social assets, brand review или любой prompt, где motion stability важнее скорости. Model page TheRouter описывает его как flagship text/image-to-video tier с model id doubao/doubao-seedance-2-0.

Выбирайте Seedance 2.0 Fast, когда prompt ещё меняется. Мы используем его для storyboard passes, настройки camera language и проверки reference image до финального рендера. Fast model page позиционирует его как lower-cost, lower-latency вариант для iterative video drafting.

Ссылки, которые стоит держать рядом:

• Provider hub: ByteDance / Doubao on TheRouter
• Standard model: doubao/doubao-seedance-2-0
• Fast model: doubao/doubao-seedance-2-0-fast
• Related provider guide: Volcengine Ark / Doubao API Complete Guide
• Adjacent video alternative: OpenAI Sora 2 Pro

Native Volcengine Ark task flow

Seedance API от Volcengine проще представить как очередь:

1. Submit task с model id, content references, duration, ratio, resolution и watermark preference.
2. Сохранить returned task id.
3. Poll task endpoint с exponential backoff.
4. Считать downloadable только статус succeeded.
5. Сохранить generated asset в своё storage; third-party guides сообщают об expiring output URLs, поэтому provider URL не должен быть единственной копией.

Native Ark text-to-video request выглядит так:

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic lighting"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

Native Ark model id (doubao-seedance-2-0-260128) отличается от TheRouter model id (doubao/doubao-seedance-2-0). Храните mapping в config, не размазывайте строки по business code. Source: Apidog Seedance 2.0 API walkthrough, retrieved 2026-06-26; cross-check с local TheRouter model data.

Routing Seedance через TheRouter

Для TheRouter цель integration — не скрывать асинхронность video generation. Цель — единый account, routing layer и stable model identifiers при сохранении provider task semantics.

Минимальная TypeScript shape:

const response = await fetch("https://api.therouter.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THEROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao/doubao-seedance-2-0",
    prompt: "A clean product demo shot, white background, slow orbit camera",
    seconds: 5,
    aspect_ratio: "16:9",
    size: "1080p",
  }),
});

const task = await response.json();
console.log(task.id);

Затем poll returned id:

async function waitForVideo(taskId: string) {
  for (let attempt = 0; attempt < 30; attempt++) {
    const r = await fetch(`https://api.therouter.ai/v1/videos/${taskId}`, {
      headers: { Authorization: `Bearer ${process.env.THEROUTER_API_KEY}` },
    });
    const task = await r.json();
    if (task.status === "succeeded") return task;
    if (task.status === "failed" || task.status === "expired") throw new Error(task.status);
    await new Promise((resolve) => setTimeout(resolve, Math.min(30000, 2000 * 2 ** attempt)));
  }
  throw new Error("Seedance task timed out");
}

Пример намеренно консервативный: перед production проверьте текущий media endpoint и response fields для вашего account. Правдивая capability claim: TheRouter routes media-generation jobs там, где path реализован; мы не должны утверждать normalisation каждого provider-specific field без проверки docs/code.

Text-to-video и image-to-video examples

Начните с text-to-video, чтобы изолировать главные переменные:

{
  "model": "doubao/doubao-seedance-2-0",
  "prompt": "A macro shot of a mechanical keyboard assembling itself, shallow depth of field, soft studio lighting",
  "seconds": 5,
  "aspect_ratio": "16:9",
  "size": "1080p"
}

Когда polling работает, добавьте reference image:

{
  "model": "doubao/doubao-seedance-2-0-fast",
  "prompt": "Animate the reference image into a slow dolly-in product reveal, keep the logo stable",
  "image_url": "https://example.com/reference-product.png",
  "seconds": 5,
  "aspect_ratio": "1:1",
  "size": "720p"
}

Production preference: сохраняйте original prompt, reference asset hash, model id, task id, final asset URL и provider error body. Video bugs трудно воспроизвести, если сохранить только final URL.

Pricing, latency и output retention

Local model data TheRouter сейчас зеркалит Ark video cost как per-video flat request estimate: 4.66668 для doubao/doubao-seedance-2-0 и 3.66672 для doubao/doubao-seedance-2-0-fast, с пометкой о необходимости уточнения после observed usage. Pricing page Volcengine обновлена 2026-06-23; search snippets показывают, что video price зависит от resolution, aspect ratio, input duration и output duration.

Ответственный engineering stance:

• не обещайте, что Seedance — самый дешёвый video route;
• ограничивайте duration и resolution в product UI;
• логируйте request parameters рядом с cost records;
• используйте Fast для prompt exploration, standard для final render;
• скачивайте и re-host completed videos вместо reliance on provider retention.

Sources: Volcengine Ark model pricing, local docs/lib/models-data.ts, Apidog Seedance API walkthrough. Retrieved 2026-06-26.

Common errors and fixes

Чеклист перед продакшеном

• Храните model ids в config: doubao/doubao-seedance-2-0 и doubao/doubao-seedance-2-0-fast.
• Добавьте idempotency на task submission, чтобы retries не создавали duplicate videos.
• Poll with exponential backoff и upper timeout.
• Сохраняйте prompt, model, parameters, task id, status history, cost estimate и final asset URL.
• Download completed videos в durable storage.
• Показывайте Fast vs standard как product choice, а не hidden random router decision.
• Свяжите internal docs с TheRouter ByteDance provider page и обеими Seedance model pages для проверки metadata.

FAQ

Seedance 2.0 OpenAI-compatible?

Native Volcengine task API — не обычный chat-completions call; это video task API. TheRouter может быть routing layer для media-generation jobs там, где path реализован, но video generation всё равно нужно считать async, а не blocking OpenAI chat response.

Какой model id использовать на TheRouter?

doubao/doubao-seedance-2-0 для standard quality и doubao/doubao-seedance-2-0-fast для faster iteration. Native Ark ids включают date-stamped names вроде doubao-seedance-2-0-260128.

Можно ли отправлять images как references?

Да. TheRouter model metadata указывает text и image inputs с video output для обоих Seedance 2.0 variants, а ByteDance описывает Seedance 2.0 как multimodal reference model. Перед bulk workflow проверьте точный image field shape выбранного endpoint.

Сколько ждать polling?

Используйте product-level timeout, а не фиксированное число из статьи. Начните с 2-5 second intervals, back off к 30 seconds и показывайте task пользователю, если provider queue медленная.

Нужно ли все video jobs сначала гонять через Fast?

Нет. Fast полезен, пока prompt не стабилен; standard — когда storyboard или reference image уже подтверждены человеком. Так вы экономите cost без скрытия quality tradeoffs.