# Seedance 2.5 · Special — /videos/generations

Целая длительность 4–30 с, 720P, 16:9 или 9:16. До 30 референсных изображений и 10 аудиофайлов; референсное видео не поддерживается. Без референсного аудио — $2 (400 кредитов), с ним — $3 (600 кредитов) за ролик независимо от длительности. Созданная звуковая дорожка не считается референсным аудио. Предложение временное, постоянная доступность не гарантируется. Время зависит от очереди; проверяйте исходную задачу, не отправляйте повторно. При сбое — полный возврат.

**Эндпоинт:** `POST https://kovapi.com/v1/videos/generations`

## Быстрый старт

Три шага: отправить задачу, опросить её и забрать ссылку на видео. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть.

**Шаг 1 · Отправка (сразу возвращает id задачи, HTTP 202)**

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-30s", "prompt": "Путешественник идёт через осенний городок в долине от рассвета до заката, камера следует за ним всю дорогу", "duration": 25, "resolution": "720P", "size": "16:9"}'
```

Ответ (HTTP 202)

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "seedance-2.5-30s"
}
```

**Шаг 2 · Опрашивайте каждые 5–10 секунд, пока `status` не станет `succeeded` или `failed`**

```
curl https://kovapi.com/v1/videos/jobs/img_5c2e8f1a9b3d7e6f0a4c8b2d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Ответ при успехе

```
{
  "id": "img_5c2e8f1a9b3d7e6f0a4c8b2d",
  "object": "video.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "seedance-2.5-30s",
  "data": [
    {"url": "https://img.kovapi.com/i/8c1f0e5d2b7a49e3a6d0c4f1b9e2a7d5.mp4"}
  ],
  "usage": {"clips": 1, "model": "seedance-2.5-30s"}
}
```

**Шаг 3 · `data[0].url` — это ролик (MP4). Он хранится 15 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.**

**Полный пример (Python: отправить, дождаться, сохранить на диск)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. отправка
job = requests.post(f"{BASE}/videos/generations", headers=HEADERS, json={
    "model": "seedance-2.5-30s",
    "prompt": "Путешественник идёт через осенний городок в долине от рассвета до заката, камера следует за ним всю дорогу",
    "duration": 25,
    "resolution": "720P",
    "size": "16:9",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. опрос каждые 10 секунд, не дольше часа
deadline = time.time() + 3600
while job["status"] not in ("succeeded", "failed") and time.time() < deadline:
    time.sleep(10)
    job = requests.get(f"{BASE}/videos/jobs/{job['id']}", headers=HEADERS).json()

# 3. скачивание видео
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("seedance-2.5-30s.mp4", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
elif job["status"] == "failed":
    print("failed:", job["error"]["code"], job["error"]["message"])
else:
    print("still", job["status"], job["id"])
```

Пока задача в очереди, опрос также возвращает `queue_position` (сколько задач впереди вашей) и `eta_seconds` (ожидаемое время ожидания). Если ваш лимит ожидания истёк, не отправляйте задачу заново: она никуда не делась, продолжайте опрашивать тот же id позже.

## Аутентификация
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Основные характеристики

| Длительность | 4–30 с |
| --- | --- |
| Разрешение | 720P |
| Пропорции | 16:9 / 9:16 |
| Референсные изображения | до 30 · используются как референсы (персонажи, сцена, стиль), но не как кадр |
| Референсные видео | не поддерживается |
| Референсное аудио | до 10 |
| Звук | всегда включён; отключить нельзя (`audio: false` отклоняется) |
| Оплата | за ролик: одна цена при любой длительности |

## Параметры запроса

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| model | string | Да | Model ID, here seedance-2.5-30s. |
| prompt | string | Да | Опишите содержание, камеру и действия. |
| duration | integer | Нет | Any integer from 4 to 30 seconds (default 30). Alias: seconds. Duration does not change the per-clip price. |
| resolution | string | Нет | 720P |
| size | string | Нет | Aspect ratio: 16:9 / 9:16 (default 16:9); alias aspect_ratio. 21:9 is not available on this model. |
| image | string | Нет | Image-to-video: include a reference image (public URL, data: URI or base64); omit for text-to-video. |
| images | array | Нет | Multiple reference images, up to 30. Exceeding the cap is rejected, never truncated. Alias: reference_images. |
| audio_reference | string / array | Нет | Публичный HTTPS URL или массив, до 10 файлов; требуется хотя бы одно изображение. MP3/WAV/M4A, до 15 МБ и 30 с каждый. С референсным аудио: $3 (600 кредитов) за ролик. |
| audio | boolean | Нет | Каждый ролик выходит со звуком, отключить его нельзя; `false` отклоняется (400), поэтому не передавайте этот параметр. |
| callback_url | string | Нет | Куда отправить результат, когда задача завершится; подробнее — в разделе о вебхуках ниже. |
| n | integer | Нет | Каждая задача создаёт один ролик; передавать параметр не нужно. При значении больше 1 всё равно создаётся один ролик, но при отправке резервируется стоимость n роликов, а лишнее возвращается после завершения задачи. |

## Цена

Временно доступно · за ролик

|  | Кредитов за ролик | USD за ролик |
| --- | --- | --- |
| Без референсного аудио | 400 | $2.00 |
| С референсным аудио | 600 | $3.00 |

Целая длительность 4–30 с, 720P, 16:9 или 9:16. До 30 референсных изображений и 10 аудиофайлов; референсное видео не поддерживается. Без референсного аудио — $2 (400 кредитов), с ним — $3 (600 кредитов) за ролик независимо от длительности. Созданная звуковая дорожка не считается референсным аудио. Предложение временное, постоянная доступность не гарантируется. Время зависит от очереди; проверяйте исходную задачу, не отправляйте повторно. При сбое — полный возврат.

## Референсные материалы

Целая длительность 4–30 с, 720P, 16:9 или 9:16. До 30 референсных изображений и 10 аудиофайлов; референсное видео не поддерживается. Без референсного аудио — $2 (400 кредитов), с ним — $3 (600 кредитов) за ролик независимо от длительности. Созданная звуковая дорожка не считается референсным аудио. Предложение временное, постоянная доступность не гарантируется. Время зависит от очереди; проверяйте исходную задачу, не отправляйте повторно. При сбое — полный возврат.

Референсные изображения (не более 30) задают персонажей, сцену и стиль и никогда не используются как кадр; в промпте ссылайтесь на них как `@Image1`, `@Image2`.

Реальные человеческие лица подходят в качестве референсных изображений, маскирование не требуется. Пожалуйста, убедитесь, что у вас есть право использовать внешность людей, изображённых на фото.

```
{
  "model": "seedance-2.5-30s",
  "prompt": "Follow @Image1 and use @Audio1 as the soundtrack",
  "duration": 25, "resolution": "720P", "size": "16:9",
  "images": ["https://example.com/reference.png"],
  "audio_reference": ["https://example.com/reference.mp3"]
}
```

## Требования к контенту

Каждая задача Seedance проходит проверку контента: промпт, файлы-референсы и готовый ролик — и изображение, и звук. Задача, не прошедшая проверку, завершается с `content_policy`, деньги не списываются.

### Когда идёт проверка

При отправке проверяются промпт и референсы; после генерации ролика ещё раз проверяются изображение и звук. Поэтому отказ может прийти через несколько секунд после отправки или только после окончания рендера (это может занять больше получаса). Задача, завершившаяся со `status` `failed` и `error.code` `content_policy`, не прошла проверку; с вебхуком придёт событие `video.failed`.

### Без оплаты

Отклонённая задача ничего не стоит: сумма, зарезервированная при отправке, полностью возвращается по завершении задачи, а в журнале вызовов она отмечена как неоплаченная.

### Звук

Звук (реплики, закадровый текст, пение и эффекты) модель генерирует по промпту, и он проверяется вместе с изображением: реплики, закадровый текст и тексты песен из промпта озвучиваются или поются. Если в ролике не нужны голоса, не пишите в промпте реплики и тексты песен. Эта модель всегда добавляет звук, отключить его нельзя. Загруженное аудио-референс тоже проверяется; музыка, защищённая авторским правом, в качестве референса может быть отклонена.

### Что чаще всего отклоняется

- Сексуальный контент, обнажённость или сексуальные намёки, в том числе изображения, созданные или смонтированные с помощью ИИ

- Кровь, жестокость, самоповреждение и насильственные травмы, например огнестрельные ранения и кровотечение

- Огнестрельное оружие, взрывчатка и наркотики

- Любой сексуализированный контент с несовершеннолетними; несовершеннолетние рядом с алкоголем, табаком, наркотиками или в опасных ситуациях тоже отклоняются

- Политики, знаменитости, спортсмены, бизнесмены и другие публичные лица — внешность или голос, включая двойников

- Персонажи и объекты, защищённые авторским правом, например персонажи Disney или Marvel

- Контент с ненавистью или дискриминацией, фейковые новости

### Длинные сценарии

Одна сцена с нарушением отклоняет весь ролик, и чаще всего это случается в длинных раскадровочных сценариях: перестрелка или крупный план крови в экшен-сцене, несовершеннолетние, которые пьют или курят, — и весь ролик не пройдёт. Перед отправкой прочитайте сценарий целиком и удалите или перепишите такие сцены.

### Реальные люди

Чтобы использовать фото реального человека как референс, нужно право на использование его изображения.

### После отказа

Повторная отправка того же самого снова будет отклонена. Найдите часть, которая скорее всего нарушает правила, перепишите промпт или замените референс и отправьте заново.

Код ошибки: `content_policy` · `status: failed`

`upstream_line_unavailable`: При перегрузке сервиса или исчерпании доступных ресурсов возвращается upstream_line_unavailable. Неудачные задания не оплачиваются, зарезервированные кредиты возвращаются; повторите попытку позже. Эта ошибка не указывает на конкретную проблему параметров или материалов. Явные ограничения длительности, недоступные материалы и отклонения проверки сохраняют коды duration_rejected, reference_unreadable и content_policy; следуйте соответствующим рекомендациям.

## Статус задачи и поля ответа

`GET /v1/videos/jobs/{id}` возвращает эти статусы; все поля описаны в разделе [Асинхронные задачи](https://docs.kovapi.com/ru/guide/async-jobs#fields). Опрашивайте каждые 5–10 секунд или получайте результат вебхуком (см. ниже). Опрос бесплатный, и прочитать задачу может любой ключ того же аккаунта.

| Статус | Что значит |
| --- | --- |
| queued | В очереди. В ответе есть `queue_position` (сколько задач впереди) и `eta_seconds` (ожидаемое время ожидания). |
| processing | Генерируется. |
| succeeded | Готово. Результат в `data[0].url`, детали оплаты в `usage`. |
| failed | Ошибка. Причина в `error`; зарезервированные кредиты возвращаются полностью. |

- `processing` может снова смениться на `queued`: например, при высокой нагрузке, пока готовый ролик скачивается повторно или после перезапуска сервиса. Если задачу не удалось выполнить, шлюз может автоматически запустить рендер заново; сколько бы ни было повторов, задача оплачивается один раз.

- Один аккаунт выполняет до 50 задач одновременно; остальные ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, ссылки на видео — 15 дней.

## Сколько ждать

Целая длительность 4–30 с, 720P, 16:9 или 9:16. До 30 референсных изображений и 10 аудиофайлов; референсное видео не поддерживается. Без референсного аудио — $2 (400 кредитов), с ним — $3 (600 кредитов) за ролик независимо от длительности. Созданная звуковая дорожка не считается референсным аудио. Предложение временное, постоянная доступность не гарантируется. Время зависит от очереди; проверяйте исходную задачу, не отправляйте повторно. При сбое — полный возврат.

## Ошибки и возвраты

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе [Коды ошибок](https://docs.kovapi.com/ru/guide/errors).

### Ошибки при отправке

| HTTP | code | Причина | Что делать |
| --- | --- | --- | --- |
| 400 | invalid_request | Недопустимый параметр: длительность, разрешение, пропорция или число референсов выходят за пределы, допустимые для этой модели; промпт слишком длинный; не удаётся прочитать референсное изображение или видео; передан `audio: false` модели, ролики которой всегда со звуком, и т. п. Что именно не так, указано в `message`. | Исправьте то, что указано в `message`, и отправьте снова. |
| 400 | invalid_callback_url | `callback_url` — не публичный адрес http(s) или длиннее 2000 символов. | Укажите адрес, доступный из интернета. |
| 400 | model_not_found | ID модели написан с ошибкой, `model` не передан или модель нельзя использовать на этом эндпоинте (например, чат-модель на эндпоинте изображений). | Берите ID модели из `GET /v1/models` или из [справочника API](https://docs.kovapi.com/ru/api). |
| 401 | invalid_api_key | Ключ не существует, удалён или отключён, либо отключён аккаунт. | Проверьте ключ на странице API Keys в консоли. |
| 402 | insufficient_quota | Баланса не хватает, чтобы зарезервировать стоимость этого запроса. Шлюз сначала резервирует максимально возможную стоимость запроса, поэтому ошибка может возникнуть и при всплеске одновременных вызовов. | Если был всплеск запросов, подождите несколько секунд и повторите; в остальных случаях пополните баланс. |
| 429 | rate_limit_exceeded | Превышен лимит запросов в минуту, заданный для этого ключа (считается за последние 60 секунд). Заголовка `Retry-After` нет. | Подождите несколько секунд и повторите или увеличьте лимит ключа в консоли. |
| 503 | model_maintenance | Модель на обслуживании и не принимает запросы; пока идёт обслуживание, другая модель вместо неё не ответит. | Повторите, когда обслуживание закончится; ход работ — на [странице статуса](https://kovapi.com/ru/status). |
| 503 | service_unavailable | Временный сбой на нашей стороне, например при сохранении референсного файла. Задача не создана, ничего не списано. | Повторите чуть позже. |

### Неудачные задачи (`status` — `failed`)

| code | Когда возникает | Что делать |
| --- | --- | --- |
| content_policy | Видео: промпт, референс или сгенерированный видеоряд либо звук не прошли проверку контента (если отклонён звук, `param` равен `audio`). Wan Standard и Prime: исходные материалы не прошли проверку. `error.reason` — `FaceDetectionSuspect` (предположительно лицо реального человека) или `DataInspectionFailed` (отклонён входной контент). В `error.message` указаны причина и рекомендуемые изменения. Неудачные задания не оплачиваются. | Перепишите промпт или замените референс и только потом отправляйте снова: те же входные данные будут отклонены повторно. |
| duration_rejected | Видео: длительность не принята. Чаще всего референсное аудио или видео длиннее допустимого, пусть даже на долю секунды. | Обрежьте референсное аудио или видео до допустимой длины и отправьте снова: те же входные данные снова не пройдут. |
| reference_unreadable | Видео: модели не удалось скачать референсное изображение, видео или аудио; чаще всего ссылка ведёт на веб-страницу (YouTube, страница облачного диска). | Укажите ссылку, которая ведёт прямо на файл, или загрузите файл в Playground: те же входные данные снова не пройдут. |
| invalid_video_request | Параметры или референсы не приняты при отправке; генерация не начиналась. | Проверьте длительность, формат и референсы и отправьте снова. Оплата не списывается. |
| special_failed | Генерация не удалась, ролик не создан. | Оплата не списывается. Можно отправить задачу повторно без изменений. |
| special_unknown | Не было чёткого ответа, принята ли отправка. Чтобы не генерировать дважды, повторно её не отправляли. | Оплата не списывается. Можно отправить снова. |
| special_fetch | Ролик создан, но файл не удалось получить после нескольких попыток. | Оплата не списывается. Отправьте задачу снова. |
| special_unavailable | Тариф был недоступен, или задача не запустилась за 120 минут. | Оплата не списывается. Попробуйте позже. |

Ориентируйтесь на `code`, а не на текст `message`. Любой незнакомый `code` (или его отсутствие) обрабатывайте как `upstream_error`: повторная отправка обычно проходит успешно. За каждую неудачную задачу деньги возвращаются полностью.

## Вебхуки вместо опроса

Добавьте при отправке `callback_url` — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». [Документация по вебхукам →](https://docs.kovapi.com/ru/webhooks)

```
curl https://kovapi.com/v1/videos/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "seedance-2.5-30s", "prompt": "Путешественник идёт через осенний городок в долине от рассвета до заката, камера следует за ним всю дорогу", "duration": 25, "resolution": "720P", "size": "16:9", "callback_url": "https://your-domain.com/webhook"}'
```