Seedance 2.5 API: ID модели, Python и Node.js без путаницы маршрутов

На 4 августа 2026 года ByteDance уже представила Seedance 2.5 как продукт, однако публичные документы BytePlus по созданию видео и таблица моделей всё ещё перечисляют серию Seedance 2.0. Официально подтверждены возможности 2.5, но проверяемого first-party ID ModelArk для 2.5 пока нет. Поэтому копировать «похожий» ID недостаточно: адрес API, ключ, пространство имён модели и пути create/status должны принадлежать одному владельцу.

Что уже опубликовано для Seedance 2.5, а чего ещё нет

Страница Seedance 2.5 подтверждает ролики до 30 секунд, два продления, улучшенную работу с референсами и редактированием, white-model control и green-screen editing. На этой странице нет API host, порядка выдачи ключа, ID модели или схемы запроса.

BytePlus create API, обновлённый 31 июля 2026 года, по-прежнему описывает серию 2.0. В публичной таблице моделей и цен также есть только три ID 2.0. Строку dreamina-seedance-2-5-260628 из сторонней страницы нельзя выдавать за опубликованный BytePlus ID.

Если сервис нужен сегодня, используйте подтверждённый fallback 2.0. Если обязательна версия 2.5, дождитесь её в first-party каталоге аккаунта либо используйте gateway, который явно документирует собственные host, key, model ID, endpoint, тарификацию и ограничения. Alias такого gateway нельзя переносить в BytePlus или Volcengine.

После create API возвращает ID асинхронной задачи, а не готовое видео. Сохраните этот ID в локальном журнале; callback используйте для быстрой доставки событий, а polling — для восстановления пропущенных уведомлений. Это два канала обновления одной записи, а не две независимые генерации.

1. Сначала отличите текущий контракт от старого примера

Перед копированием кода проверьте пять признаков:

1. Кто владеет ключом: BytePlus, Volcengine или конкретный gateway.
2. Какой полный адрес указан рядом с примером.
3. К какому пространству относится ID модели: dreamina-* или doubao-*.
4. Возвращает ли create ID задачи и каким путём эта задача читается.
5. Когда обновлялись первичный документ и список моделей.

Для международного прямого доступа владельцами текущих значений служат BytePlus create API, руководство по серии Seedance 2.0 и страница управления API-ключами. Китайский контракт проверяется по Volcengine Ark API, а relay — только по документации laozhang.ai.

Русский текст, удобный интерфейс или пример с названием Seedance сами по себе не делают страницу владельцем upstream-контракта. Если в примере фигурирует 1.x, собственный путь вроде /v1/media/create или произвольный alias модели, используйте его только с ключом того же поставщика. Не переносите такие значения в BytePlus или Volcengine.

2. Зафиксируйте один маршрутный контракт

В BytePlus ключ создаётся внутри resource project. Его можно ограничить моделью или custom endpoint и списком разрешённых IP. Секрет хранится только на сервере: не помещайте его в браузерный JavaScript, мобильное приложение, URL или публичный репозиторий. Наличие ID в документации не доказывает, что модель активна для вашей учётной записи и региона; перед вызовом проверьте активацию и доступный пакет ресурсов.

Standard предназначен для приоритета качества, Fast — для баланса скорости и стоимости, Mini — для сценария с упором на экономичность. Это описание выбора внутри BytePlus, а не универсальные псевдонимы. Для китайского Mini нельзя выводить суффикс по аналогии: берите его только из текущего списка моделей своей учётной записи. Цена обновляется отдельно от API-контракта и разбирается в гайде по стоимости Seedance 2.

3. Подключите Python или Node.js к выбранному контракту

В обоих примерах значения берутся из серверных переменных SEEDANCE_BASE_URL, SEEDANCE_API_KEY и SEEDANCE_MODEL. ID может быть подтверждённым fallback 2.0 или ID 2.5 конкретного gateway, но только если его документация использует такой же Ark-образный путь.

Python

python
import os, time, requests

base = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['SEEDANCE_API_KEY']}", "Content-Type": "application/json"}
payload = {
    "model": os.environ["SEEDANCE_MODEL"],
    "content": [{"type": "text", "text": "Медленный студийный план керамической чашки"}],
    "ratio": "16:9", "resolution": "720p", "duration": 5, "generate_audio": True,
}
r = requests.post(f"{base}/contents/generations/tasks", headers=headers, json=payload, timeout=30)
r.raise_for_status()
task_id = r.json()["id"]  # Сохраните ID до polling.

while True:
    r = requests.get(f"{base}/contents/generations/tasks/{task_id}", headers=headers, timeout=30)
    r.raise_for_status()
    task = r.json()
    if task["status"] in {"succeeded", "failed", "expired"}:
        print(task)
        break
    time.sleep(5)

Node.js 18+

js
const base = process.env.SEEDANCE_BASE_URL.replace(/\/$/, "");
const headers = { Authorization: `Bearer ${process.env.SEEDANCE_API_KEY}`, "Content-Type": "application/json" };
async function call(path, init = {}) {
  const r = await fetch(`${base}${path}`, { ...init, headers: { ...headers, ...init.headers } });
  const type = r.headers.get("content-type") || "";
  if (!type.includes("application/json")) throw new Error(`Ожидался JSON, получен ${type}`);
  const data = await r.json();
  if (!r.ok) throw new Error(`${r.status}: ${JSON.stringify(data)}`);
  return data;
}
const created = await call("/contents/generations/tasks", {
  method: "POST",
  body: JSON.stringify({ model: process.env.SEEDANCE_MODEL, content: [{ type: "text", text: "Slow studio shot of a ceramic cup" }], ratio: "16:9", resolution: "720p", duration: 5, generate_audio: true }),
});
const taskId = created.id; // Сначала сохраните.
for (;;) {
  const task = await call(`/contents/generations/tasks/${taskId}`);
  if (["succeeded", "failed", "expired"].includes(task.status)) { console.log(task); break; }
  await new Promise(resolve => setTimeout(resolve, 5000));
}

Если POST завершился таймаутом до получения ID, не отправляйте второй create автоматически: первый запрос мог быть принят. Зафиксируйте неизвестный результат отправки и сверяйте callback, журнал запросов или данные поставщика.

4. Отправьте минимальный вызов и ведите единый журнал

Ниже приведён вызов только для международного BytePlus AP. Если выбран другой маршрут, одновременно меняются адрес, ключ, ID модели и пути.

bash
export ARK_API_KEY="replace-with-server-side-secret"

curl -X POST \
  "https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "dreamina-seedance-2-0-260128",
    "content": [{
      "type": "text",
      "text": "Product on a clean studio table, one slow camera arc, neutral daylight"
    }],
    "ratio": "16:9",
    "duration": 5,
    "generate_audio": false,
    "priority": 3,
    "callback_url": "https://example.com/webhooks/seedance"
  }'

Для endpoint-based online inference Seedance 2.0 поле priority принимает целые числа от 0 до 9. Большее значение продвигает ожидающую задачу только внутри того же endpoint. Оно не прерывает уже выполняемую задачу, не сравнивает разные endpoints, не относится к offline flex inference и не гарантирует более быструю генерацию.

Create response означает только приём задачи. До отправки создайте локальную запись, а после ответа атомарно добавьте providerTaskId:

ts
type LocalSeedanceJob = {
  localJobId: string;
  route: "byteplus-ap" | "volcengine-cn" | "laozhang-relay";
  requestHash: string;
  providerTaskId?: string;
  state: "submitting" | "queued" | "running" | "succeeded" | "failed" | "expired";
  lastEventId?: string;
  storedResult?: string;
};

В requestHash включите маршрут, ID модели, нормализованный prompt, идентификаторы входных материалов и параметры результата. Это ваша защита от двойного create, а не гарантия дедупликации со стороны поставщика.

Текущий контракт BytePlus разрешает необязательный callback_url. Payload имеет форму retrieve-task response; состояния — queued, running, succeeded, failed, expired. Для неудачной доставки terminal-события succeeded или failed документация указывает три повторные попытки, если за пять секунд не получено успешное подтверждение. Публичный документ не даёт основания обещать определённую webhook signature.

ts
const order = { queued: 0, running: 1, succeeded: 2, failed: 2, expired: 2 } as const;
const terminal = new Set(["succeeded", "failed", "expired"]);

async function acceptSeedanceEvent(event: {
  id: string;
  status: keyof typeof order;
}) {
  const job = await jobs.findByProviderTaskId(event.id);
  if (!job) return { status: 404 };

  const eventId = `${event.id}:${event.status}`;
  if (job.lastEventId === eventId) return { status: 204 };
  const currentOrder = job.state === "submitting" ? -1 : order[job.state];
  if (terminal.has(job.state) || order[event.status] < currentOrder) {
    await events.recordIgnored(job.localJobId, event);
    return { status: 204 };
  }

  await jobs.applyProviderState(job.localJobId, event.status, eventId, event);
  if (event.status === "succeeded") await queues.enqueueResultCopy(job.localJobId);
  return { status: 204 };
}

Обработчик должен проверять HTTPS, тип и размер тела, известный ID задачи и допустимый переход состояния, быстро отвечать 2xx и переносить скачивание в очередь. Отдельный процесс сверки читает незавершённые задачи по тому же маршруту:

bash
curl -X GET \
  "https://ark.ap-southeast.bytepluses.com/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

Если create завершился timeout до сохранения ID, найдите запись по requestHash, проверьте, не записал ли ID другой процесс, и используйте доступный у поставщика поиск или сверку. Пока отсутствие принятой задачи не доказано, помечайте результат как неопределённый и не отправляйте второй платный create.

5. Диагностируйте симптом на правильном слое

18 июля 2026 года без реальных ключей были отправлены POST-запросы с телом {}. BytePlus AP, Volcengine CN и правильный путь laozhang.ai ответили JSON 401. Путь laozhang.ai без /seedance ответил JSON 404, а устаревший /seedance/v3/... вернул HTML 200. Это проверка маршрута и границы аутентификации, не доказательство доступа к модели.

После succeeded проверьте status и media type скачивания, скопируйте результат в собственное object storage и запишите storedResult. В этом запуске срок жизни output URL не был подтверждён заново, поэтому статья не обещает конкретное время хранения. Реальные ключи не использовались; успешная генерация, latency, quota и доступность из России не проверялись.

6. Соблюдайте stop rules выбранного поставщика

• BytePlus direct выбирайте, если нужны официальное владение международной учётной записью, текущий каталог Standard/Fast/Mini или управление endpoint. Остановитесь, если модель не видна в вашей учётной записи или проект и регион ключа не совпадают.
• Volcengine direct подходит для китайской инфраструктуры и контракта doubao-*. Не переносите туда международный dreamina-* и не выводите Mini ID самостоятельно.
• laozhang.ai relay полезен, когда единый gateway и документированный Seedance route упрощают эксплуатацию. Перейдите на официальный direct route, если relay не показывает нужный регион, вариант модели, контроль учётной записи или функцию. Текущая документация relay не поддерживает workflow с лицом реального человека; соответствующие границы описаны в гайде по реальным людям.

Выбор других поставщиков относится к сравнению Seedance 2 API, а проектирование prompt и references — к практическому prompt-гайду. На этой странице не фиксируются цена, бесплатные кредиты или универсально «лучший» маршрут.

Перед production проверьте одну строку контракта целиком: модель активна в нужном проекте, секрет остаётся на сервере, локальная запись существует до submit, task ID сохраняется один раз, lastEventId обновляется вместе с состоянием, callback и polling пишут в один reducer, timeout не запускает blind resubmit, а результат копируется в собственное хранилище. Если первые четыре условия не выполнены, платную задачу отправлять рано.