> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# seedance-2 Генерация видео

> Генерация видео с помощью seedance-2, seedance-2-fast и seedance-2-mini

> [!NOTE]
>
> **Для пользователей из материкового Китая:** используйте `https://toapis.cn` в качестве эндпоинта (Base URL). Замените `https://toapis.com` на `https://toapis.cn` во всех примерах этого документа.

* Поддерживаются `seedance-2`, `seedance-2-fast` и `seedance-2-mini`
* Поддерживаются text-to-video и мультимодальный reference-to-video; `seedance-2` и `seedance-2-fast` также поддерживают сценарии с первым и последним кадром
* Поддерживаются совместные image / video / audio reference; для `seedance-2-mini` лимиты составляют `9` изображений, `3` видео и `3` аудио
* Асинхронный сценарий: submit API возвращает `generation.task`, а готовый результат забирается через API статуса задачи

## Authorizations

**Authorization** `string` *required*

Все запросы требуют Bearer Token аутентификацию.

Получить API Key можно на странице [API Key Management Page](https://toapis.com/console/token).

```
Authorization: Bearer YOUR_API_KEY
```

## Тело запроса

**model** `string` *required* (default: seedance-2)

Название модели генерации видео.

Доступные модели:

* `seedance-2` - стандартная версия для более качественного результата и полного Seedance 2 workflow
* `seedance-2-fast` - быстрая версия для превью и низкой задержки
* `seedance-2-mini` - облегченная версия для недорогих черновиков и мультимодальных reference workflow, сейчас всегда создает `1` результат за запрос

**prompt** `string`

Текстовый prompt для видео.

Рекомендуется явно описывать сцену, движение камеры, действие, стиль и аудио-настроение.

**client\_business\_id** `string`

Ваш бизнесовый ID, например номер заказа или внутренний ID задачи. Он сохраняется вместе с задачей и может использоваться для последующего запроса статуса:
`GET /v1/videos/generations/{client_business_id}`.

Также поддерживается `metadata.client_business_id`, но рекомендуется верхнеуровневое поле.

**duration** `integer` (default: 0)

Длительность видео в секундах.

Правила:

* `seedance-2`: `4-15`
* `seedance-2-fast`: `4-15`
* `seedance-2-mini`: `4-15`
* `0`: авто-длительность (только `seedance-2` / `seedance-2-fast`)
* `-1`: авто-длительность (только `seedance-2` / `seedance-2-fast`)

**aspect\_ratio** `string`

Соотношение сторон видео.

Варианты:

* `21:9`
* `16:9`
* `4:3`
* `1:1`
* `3:4`
* `9:16`
* `adaptive`

`adaptive` позволяет upstream выбрать подходящее соотношение по входным media.

**image\_urls** `string[]`

Массив URL изображений в режиме совместимости.

Рекомендуется использовать `image_with_roles`, чтобы явно задавать `first_frame`, `last_frame` или `reference_image`.

> [!WARNING]
>
> * Не используйте `image_urls` одновременно с `image_with_roles`.
> * Для новых интеграций используйте `image_with_roles`, чтобы явно указать назначение каждого изображения.

**image\_with\_roles** `array`

Список изображений с ролями.

Поддерживаемые сценарии:

* `seedance-2` / `seedance-2-fast` / `seedance-2-mini`
  * `first_frame` для генерации по первому кадру
  * `first_frame` + `last_frame` для first-last-frame генерации
  * `reference_image` для мультимодального reference режима

**Описание полей**

**url** `string` *required*

URL изображения.

**role** `string` *required*

Роль изображения.

Разрешенные значения:

* `first_frame`
* `last_frame`
* `reference_image`

> [!WARNING]
>
> * Максимум `1` `first_frame`
> * Максимум `1` `last_frame`
> * Максимум `9` `reference_image`
> * Frame mode и reference mode нельзя смешивать
> * `seedance-2-mini` также поддерживает `first_frame`, `last_frame` и `reference_image`

**video\_with\_roles** `array`

Список видео с ролями.

В мультимодальном reference режиме сейчас поддерживается только `reference_video`.

**Описание полей**

**url** `string` *required*

URL видео.

**role** `string` *required*

Фиксированное значение:

* `reference_video`

Ограничения:

* `seedance-2-mini`: до `3` reference video

**audio\_with\_roles** `array`

Список аудио с ролями.

В мультимодальном reference режиме сейчас поддерживается только `reference_audio`.

**Описание полей**

**url** `string` *required*

URL аудио.

**role** `string` *required*

Фиксированное значение:

* `reference_audio`

Ограничения:

* `seedance-2-mini`: до `3` reference audio

> [!WARNING]
>
> `audio_with_roles` нельзя использовать само по себе. Нужен хотя бы один визуальный input.

**resolution** `string` (default: 720p)

Разрешение видео.

Варианты:

* `seedance-2`: `480p`, `720p`, `1080p`, `4k`
* `seedance-2-fast`: `480p`, `720p`
* `seedance-2-mini`: `480p`, `720p`

**generate\_audio** `boolean` (default: true)

Генерировать ли синхронное аудио.

`seedance-2-mini` также поддерживает это поле.

**return\_last\_frame** `boolean` (default: false)

Возвращать ли изображение последнего кадра созданного видео.

При значении `true` URL изображения возвращается в `result.data[0].last_frame_url` после завершения задачи.

**tools** `array`

Инструменты, доступные модели. Серия Seedance 2 сейчас поддерживает веб-поиск:

```json theme={null}
[{ "type": "web_search" }]
```

Фактическое число поисков возвращается в `usage.tool_usage.web_search`; значение `0` означает, что поиск не выполнялся.

> [!WARNING]
>
> `tools` поддерживается только для text-to-video и не может использоваться вместе с изображениями, видео или аудио.

**seed** `integer`

Random seed для контроля генерации.

**callback\_url** `string`

Стандартный callback ToAPIs. Сначала настройте URL и secret Token; разрешено только same-origin переопределение. См. [Webhook](https://docs.toapis.com/docs/ru/api-reference/webhooks/task-webhooks.md).

**trace\_id** `string`

Поле трассировки клиента, не зависящее от Webhook.

**disable\_nsfw** `boolean` (default: false)

При значении `true` генерация NSFW-контента запрещена.

## Проверка материалов

Если запрос содержит изображения, видео или аудио, некоторые каналы автоматически проверяют материалы перед отправкой на генерацию. Дополнительный параметр не нужен: передавайте URL материалов в прежних полях медиа.

* Принятый запрос сразу возвращает видеозадачу. Если нужна проверка, задача остается в `queued`, а генерация отправляется только после того, как все материалы запроса пройдут проверку. Первая проверка может занять несколько минут; повторное использование того же URL тем же пользователем в том же канале переиспользует результат проверки.
* Один раунд подготовки материалов по умолчанию длится не более 20 минут. Отказ в проверке или тайм-аут подготовки завершают задачу со статусом `failed`, причина указана в `error.message`. Если проверка не пройдена, плата за генерацию видео не взимается.
* Материалы передаются только публичными HTTP(S) URL; Base64 и локальные пути не принимаются. Изображения должны быть не больше 20 MB (в некоторых каналах до 30 MB), видео и аудио не больше 100 MiB. Прежние ограничения форматов модели сохраняются.
* Каналы с проверкой валидируют материалы при приеме запроса: URL с учетными данными или длиннее 2048 байт, один URL с разными типами материала или более 64 ссылок на материалы в одном запросе возвращают HTTP 400 с `error.code` `invalid_private_assets`.
* Материалы определяются по URL. После изменения содержимого файла используйте новый URL.
* Прежние ссылки `asset://` выведены из использования и возвращают HTTP 400.

## Комбинации входов

Типичные поддерживаемые комбинации:

* Только текст: text-to-video
* Текст + первый кадр: генерация по первому кадру
* Текст + первый кадр + последний кадр: first-last-frame генерация
* Текст + reference images: мультимодальный reference режим
* Текст + reference video: генерация с reference видео
* Текст + reference images + reference audio: мультимодальный reference режим
* Текст + reference images + reference video + reference audio: мультимодальный reference режим

> [!WARNING]
>
> `seedance-2-mini` также поддерживает сценарии с первым кадром и первым/последним кадром. Используйте `image_with_roles` с явными ролями `first_frame` / `last_frame`.

## Возможности

| Параметр | seedance-2 | seedance-2-fast | seedance-2-mini |
| - | - | - | - |
| Позиционирование | Более высокое качество и длинные ролики | Более быстрая генерация и меньшая задержка | Недорогие черновики и мультимодальные reference |
| Длительность | `4-15` секунд, поддерживается авто-длительность | `4-15` секунд, поддерживается авто-длительность | `4-15` секунд |
| Разрешение | `480p` / `720p` / `1080p` / `4k` | `480p` / `720p` | `480p` / `720p` |
| Роли изображений | `first_frame` / `last_frame` / `reference_image` | `first_frame` / `last_frame` / `reference_image` | `first_frame` / `last_frame` / `reference_image` |
| Роли видео | `reference_video` | `reference_video` | `reference_video` |
| Роли аудио | `reference_audio` | `reference_audio` | `reference_audio` |
| Frame mode | Поддерживается | Поддерживается | Поддерживается |
| Лимит reference image | `9` | `9` | `9` |
| Лимит reference video | Зависит от выбранного routed channel | Зависит от выбранного routed channel | `3` |
| Лимит reference audio | Зависит от выбранного routed channel | Зависит от выбранного routed channel | `3` |
| Поле синхронного аудио | `generate_audio` | `generate_audio` | `generate_audio` |
| ToAPIs callback | `callback_url` (`trace_id` опционально) | `callback_url` (`trace_id` опционально) | `callback_url` (`trace_id` опционально) |

> [!NOTE]
>
> `seedance-2-mini` сейчас всегда генерирует `1` результат за запрос и не открывает `count` / `n`. Управление кадрами задавайте через `image_with_roles` с `first_frame` / `last_frame`.

> [!NOTE]
>
> Получайте готовые результаты через [Статус видеозадачи](https://docs.toapis.com/docs/ru/api-reference/tasks/video-status.md). Если передача исходного URL включена, сначала используйте `result.data[].url`, а необязательный `fallback_url` только при недоступности основного адреса. Для последнего кадра используются `last_frame_url` и `fallback_last_frame_url`. Резервные поля возвращаются только при наличии доступных копий.

## Response

**id** `string`

ID задачи для запроса статуса.

**client\_business\_id** `string`

Ваш бизнесовый ID. Возвращается только если `client_business_id` был передан в запросе.

**object** `string`

Тип объекта, всегда `generation.task`.

**model** `string`

Название модели, использованной в запросе.

**status** `string`

Статус задачи: `queued`, `in_progress`, `completed` или `failed`.

**progress** `integer`

Прогресс задачи в процентах (`0-100`).

**created\_at** `integer`

Временная метка создания задачи.

> [!NOTE]
>
> Submit API возвращает базовый объект задачи. После завершения используйте [Get Video Task Status](https://docs.toapis.com/docs/ru/api-reference/tasks/video-status.md), чтобы получить `completed_at`, `expires_at` и `result.type = "video"` вместе с `result.data[].url` и `result.data[].format`. При `return_last_frame` последний кадр возвращается в `result.data[0].last_frame_url`; при `web_search` число поисков возвращается в `usage.tool_usage.web_search`.

```bash cURL (seedance-2-mini мультимодальный reference) theme={null}
curl --request POST \
  --url https://toapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "seedance-2-mini",
    "client_business_id": "order_20260616_001",
    "prompt": "Сохрани персонажа с изображения 1, используй движение камеры из видео 1 и ритм аудио 1 для короткого indoor product ролика.",
    "duration": 10,
    "aspect_ratio": "16:9",
    "image_with_roles": [
      {"url": "https://example.com/ref-image-1.jpg", "role": "reference_image"}
    ],
    "video_with_roles": [
      {"url": "https://example.com/ref-video-1.mp4", "role": "reference_video"}
    ],
    "audio_with_roles": [
      {"url": "https://example.com/ref-audio-1.mp3", "role": "reference_audio"}
    ],
    "resolution": "480p"
  }'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://toapis.com/v1/videos/generations",
    headers={
        "Authorization": "Bearer your-ToAPIs-key",
        "Content-Type": "application/json",
    },
    json={
        "model": "seedance-2-mini",
        "prompt": "Сохрани персонажа и используй ритм reference image и reference video для короткого indoor ad clip",
        "duration": 8,
        "aspect_ratio": "16:9",
        "resolution": "720p",
        "image_with_roles": [
            {"url": "https://example.com/ref.png", "role": "reference_image"}
        ],
        "video_with_roles": [
            {"url": "https://example.com/ref.mp4", "role": "reference_video"}
        ],
    },
)

print(response.json())
```

```json 200 theme={null}
{
  "id": "tsk_vid_xxx",
  "client_business_id": "order_20260616_001",
  "object": "generation.task",
  "model": "seedance-2-mini",
  "status": "in_progress",
  "progress": 10,
  "created_at": 1781577600
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.