Seedance 2.5 | BeatAPI API Documentation

Создавайте видео длительностью 4–30 секунд в 480p, 720p или 1080p по тексту, первому и последнему кадрам либо референсам: до 30 изображений, 10 видео и 10 аудиофрагментов. Модель также позволяет редактировать и продлевать видео.

Асинхронная обработка: запрос создания возвращает ID задачи. Видео будет доступно после её успешного завершения, обычно через несколько минут.
Четыре варианта ввода: только текст, первый кадр, первый и последний кадры либо произвольное сочетание изображений, видео и аудио в качестве референсов. Допускается и одно аудио без других материалов.
Параметр task_type указывает, нужно ли использовать референсные видео для нового ролика, отредактировать видео или продлить его. Это позволяет проверить запрос до списания средств.
Звук генерируется по умолчанию без доплаты. Формат по умолчанию — MP4; при явном запросе доступен MOV.
Стоимость зависит от разрешения и длительности результата, а также от длительности референсных видео. Задача, завершившаяся ошибкой, не оплачивается.

POST/v1/videos/tasksПопробовать

Открывает модель в API Explorer. Введите свой API-ключ BeatAPI, чтобы создать задачу. Это настоящий запрос: его стоимость спишется с вашего баланса.

Идентификаторы моделей

Все четыре модели Seedance используют один адрес API. Значения ниже взяты непосредственно из контракта шлюза. Только Seedance 2.5 принимает task_type, output_format и seed.

ID модели	`duration` (с)	`resolution`	Максимум референсных изображений	Максимум референсных видео	Максимум референсных аудиофайлов	Когда выбрать
`seedance-2.5`	4–30	`480p`, `720p`, `1080p`	30	10	10	Нужны ролики до 30 секунд, много референсов, редактирование или продление видео либо результат в MOV.
`seedance-2`	4–15	`480p`, `720p`, `1080p`, `4k`	9	3	3	Нужно видео в 4K либо более низкая цена, чем у 2.5, при том же разрешении.
`seedance-2-fast`	4–15	`480p`, `720p`	9	3	3	Нужна более низкая цена в 480p или 720p с сохранением параметра `generate_audio`.
`seedance-2-mini`	4–15	`480p`, `720p`	9	3	3	Главное — минимальная цена. Разрешение 480p или 720p, без параметра `generate_audio`.

Адрес API и авторизация

POST https://api.beatapi.io/v1/videos/tasks

`Authorization` string Обязательно

Передавайте API-ключ BeatAPI как Bearer <BEATAPI_API_KEY>. Создать ключ можно в панели управления. Храните ключи на сервере, а не в коде браузерного или мобильного приложения.

Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.

Как выполняется запрос

Создайте задачу

Отправьте перечисленные ниже параметры методом POST на указанный адрес. Ответ 201 означает, что задача принята, а её стоимость зарезервирована на балансе. Обработка идёт в фоновом режиме. Сохраните data.id.

Дождитесь завершения

Вызывайте GET /v1/tasks/{task_id}, выдерживая между вызовами data.poll_after_seconds (5 с для изображений, 8 с для видео), пока status не станет succeeded или failed. Можно также настроить вебхук для событий task.succeeded и task.failed. Сохраняйте опрос как резервный способ проверки: задача, остановленная по тайм-ауту обработки, не отправляет событие.

Сохраните результат

При succeeded скачайте файлы по всем ссылкам data.output.media[].url и сохраните нужные результаты у себя. BeatAPI не гарантирует срок доступности этих ссылок. При failed прочитайте data.error_code и data.error_message: зарезервированная сумма возвращена на баланс, а data.retryable показывает, может ли повтор того же запроса завершиться успешно.

Режимы ввода

Режим	Обязательные данные	Примечания
Видео по тексту	`model`, `prompt`	Не передавайте массивы входных материалов.
Первый кадр	`model`, `prompt`, `images` (1 ссылка)	Видео начинается с переданного изображения и сохраняет его соотношение сторон.
Первый и последний кадры	`model`, `prompt`, `images` (2 ссылки)	`images[0]` — первый кадр, `images[1]` — последний.
Референсы	`model`, `prompt` и хотя бы одно из полей `reference_images`, `reference_videos`, `reference_audios`	Любое сочетание, в том числе только аудио. Нельзя сочетать с `images`. Для редактирования или продления референсного видео задайте `task_type`.

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

`model` string Обязательно

Модель, которую нужно вызвать.

Значение: seedance-2.5

Если значение неверно

Поле отсутствует: "model" is required
На этот адрес API отправлена модель изображений: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

`prompt` string Обязательно

Что должно происходить в видео: объект, действие, движение камеры, стиль и звук. Если используете референсы, укажите назначение каждого материала.

Длина: 1–5000 символов

Длина измеряется в символах. Иероглиф CJK считается одним символом.
Ссылайтесь на материалы по их порядку, например «первое референсное изображение» или «второе референсное видео».
Когда создаёте новое видео по видеореференсам, избегайте слов вроде «заменить», «удалить» или «продлить»: модель может понять их как команду редактирования. Чтобы явно задать режим, передайте task_type: "reference". Для edit опишите, что изменить и что сохранить. Для extend — что должно произойти дальше.

Если значение неверно

Поле отсутствует: "prompt" is required
Пустое значение или превышена допустимая длина: "prompt" has an unsupported length

`images` string[] Необязательно

Первый кадр либо первый и последний кадры.

Число элементов: 1–2
Каждый элемент — общедоступная ссылка https://. Если файл находится на вашем устройстве, сначала загрузите его через POST /v1/files, затем передайте полученный data.url.

Одна ссылка: видео начинается с этого изображения. Две ссылки: images[0] задаёт первый кадр, images[1] — последний.
Видео сохраняет соотношение сторон первого изображения; aspect_ratio не применяется.
Если изображений больше или они должны направлять генерацию, но не служить кадрами, используйте reference_images.

Если значение неверно

Больше двух ссылок: "images" accepts at most 2 items
Передано вместе с любым полем reference_*: Cannot combine "images" with reference inputs in one task
Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL

`reference_images` string[] Необязательно

Изображения, определяющие содержание, персонажей, товары или стиль видео.

Число элементов: 1–30
Каждый элемент — общедоступная ссылка https://. Если файл находится на вашем устройстве, сначала загрузите его через POST /v1/files, затем передайте полученный data.url.

Изображения используются в порядке списка. В промпте ссылайтесь на них по порядку.

Если значение неверно

Превышено максимальное число элементов: "reference_images" accepts at most 30 items
Передано вместе с images: Cannot combine "images" with reference inputs in one task

`reference_videos` string[] Необязательно

Видео, из которых нужно взять движение, работу камеры или содержание, либо видео для редактирования или продления (см. task_type).

Число элементов: 1–10
Каждый элемент — общедоступная ссылка https://. Если файл находится на вашем устройстве, сначала загрузите его через POST /v1/files, затем передайте полученный data.url.

Каждая ссылка должна возвращать MP4- или MOV-файл с сервера, поддерживающего запросы диапазона байтов. Шлюз измеряет длительность каждого ролика до создания задачи, поскольку секунды референсных видео оплачиваются.
Обязательно при task_type со значением edit или extend.

Каждая секунда референсного видео увеличивает стоимость (см. раздел об оплате). Обрежьте ролик до нужного фрагмента.

Если значение неверно

Превышено максимальное число элементов: "reference_videos" accepts at most 10 items
Не удалось прочитать ролик: A reference video could not be read: reference_videos[0]: its host does not allow byte-range requests. Send an MP4 or MOV file at a public HTTPS URL whose host allows byte-range requests.

`reference_audios` string[] Необязательно

Музыка, голос или звук, на которые должна ориентироваться модель. Аудио допускается и без референсных изображений или видео.

Для WAV и MP3 проверяются перечисленные ниже ограничения длительности. Другие форматы передаются модели без измерения.

Если значение неверно

Превышено максимальное число элементов: "reference_audios" accepts at most 10 items

`duration` integer НеобязательноПо умолчанию: `5`

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

По умолчанию: 5
Диапазон: 4–30

Если параметр не указан, передаётся 5, в том числе при task_type со значением auto или reference.
При task_type: "extend" всегда задавайте длительность: это полная длина результата вместе с исходным видео. Чтобы добавить 5 секунд к 5-секундному ролику, передайте 10. Если не указать параметр, будет запрошено всего 5 секунд.
При task_type: "edit" не передавайте длительность: результат сохраняет длину исходного видео.

Если значение неверно

Значение вне диапазона или не является целым числом: "duration" is outside its supported range
Передано при task_type: "edit": task_type "edit" keeps the reference video's length: leave "duration" out

`aspect_ratio` string НеобязательноПо умолчанию: `adaptive`

Соотношение ширины и высоты видео. Значение adaptive позволяет модели определить его по входным материалам.

Допустимые значения: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16
По умолчанию: adaptive

Игнорируется, если в images передан первый кадр: видео сохраняет соотношение сторон этого кадра.
При task_type со значением edit или extend не передавайте параметр либо укажите adaptive: результат сохраняет соотношение сторон исходного видео.
При adaptive или заданных кадрах сумма резерва рассчитывается для наибольшего кадра выбранного разрешения, поэтому может быть немного выше, чем при фиксированном соотношении сторон.

Если значение неверно

Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16]
Фиксированное соотношение сторон при edit или extend: task_type "edit" keeps the reference video's aspect ratio: leave "aspect_ratio" out or send "adaptive"

`resolution` string НеобязательноПо умолчанию: `720p`

Разрешение результата. Чем оно выше, тем дороже секунда видео.

Допустимые значения: 480p, 720p, 1080p
По умолчанию: 720p

Используйте только строчные буквы. Seedance 2.5 не поддерживает 4K; для этого используйте seedance-2.

Если значение неверно

Недопустимое значение, например 4k или 720P: "resolution" must be one of: [480p 720p 1080p]

`generate_audio` boolean НеобязательноПо умолчанию: `true`

Нужно ли генерировать звуковую дорожку. На цену это не влияет.

По умолчанию: true

Если значение неверно

Значение не равно true или false: "generate_audio" must be a boolean

`seed` integer Необязательно

Фиксированное число помогает воспроизводить похожие результаты. Для случайного seed не передавайте поле либо укажите -1.

Диапазон: -1–4294967295

Одинаковый seed при одинаковом запросе даёт похожие результаты, но полное совпадение не гарантируется.

Если значение неверно

Значение вне диапазона: "seed" is outside its supported range

`task_type` string Необязательно

Что делать с reference_videos: создать по ним новое видео (reference), отредактировать одно (edit) или продлить одно (extend). При auto или отсутствии поля модель определяет действие по промпту.

Допустимые значения: auto, reference, edit, extend

Явное указание типа задачи позволяет шлюзу проверить запрос до списания средств. Правила каждого типа приведены ниже в разделе «Типы задач».
При auto или reference длительность передаётся всегда: 5, если вы не указали другую. Поэтому промпт, который модель поняла как редактирование, может вызвать ошибку после отправки с возвратом средств либо повторную обработку в режиме редактирования с оплатой по длительности исходного видео. Если нужно редактирование, передавайте edit.

Если значение неверно

Значение отсутствует в списке допустимых: "task_type" must be one of: [auto reference edit extend]
edit или extend без референсного видео: task_type "edit" needs a video in "reference_videos"
reference без референсных материалов: task_type "reference" needs reference inputs

`output_format` string Необязательно

Контейнер результата: mp4 по умолчанию или mov. Цена одинакова.

Допустимые значения: mp4, mov

mov удобен для последующего монтажа, но доступен не всегда. Если формат недоступен, запрос отклоняется до списания средств; сообщение перечисляет доступные сейчас форматы.

Если значение неверно

Значение отсутствует в списке допустимых: "output_format" must be one of: [mp4 mov]

Перед созданием задачи шлюз также проверяет следующие сочетания параметров:

images нельзя сочетать с полями референсных материалов.

Ограничения входных материалов

До создания задачи шлюз проверяет каждый входной материал. Если ограничение нарушено, возвращается 400 bad_request с указанием материала. Средства не списываются.

Материал	Ограничения, проверяемые до создания задачи
Изображения	ширина и высота: 300–6000 пикс.; соотношение сторон (ширина ÷ высота): 0.4–2.5; каждый файл не более 30 MB
Видео	каждый файл: 2–30 с; суммарно не более 30 с; ширина и высота: 300–6000 пикс.; соотношение сторон (ширина ÷ высота): 0.4–2.5; 407696–8295044 пикселей в кадре (ширина × высота); 24–60 кадров/с; каждый файл не более 200 MB
Аудио	каждый файл: 2–30 с; суммарно не более 30 с; каждый файл не более 15 MB

Референсные видео должны быть в MP4 или MOV и доступны по общедоступной HTTPS-ссылке с поддержкой запросов диапазона байтов. Если длительность ролика невозможно измерить, запрос всегда отклоняется, поскольку его секунды оплачиваются.
Размер изображения проверяется, если сервер сообщает его. Используйте JPEG, PNG или WebP. Если модель не сможет использовать файл, задача завершится с bad_request после отправки, а средства будут возвращены.
Ограничения проверяются в порядке: длительность, стороны, соотношение сторон, число пикселей, частота кадров и размер файла. Сообщение указывает список и индекс материала, начиная с 0, как в ошибках полей: reference_videos[0] is 1.5 seconds long; this model takes reference video of 2 to 30 seconds.
Длительность измеряется с допуском 0,1 секунды. Размер файла проверяется только тогда, когда сервер его сообщает.
При создании задачи ссылки на изображения и аудио отклоняются только при ответе сервера 4xx или пустом файле, например images[1] could not be downloaded: the URL returned HTTP 404.. Остальные проблемы с этими материалами выявляются после отправки.
Частота 23.976 FPS считается ниже 24 и отклоняется. Экспортируйте ролик заново с частотой 24 FPS или выше.
Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

Типы задач

Требования столбцов «Обязательно» и «Не передавать» проверяются при создании задачи. Нарушающий их запрос отклоняется с 400 bad_request без списания средств.

`task_type`	Что делает	Обязательно	Не передавать
`auto` или не указано	По промпту модель определяет, служат ли референсные видео материалом для нового ролика, требуют редактирования или продления.	—	—
`reference`	Новое видео по референсам.	Хотя бы одно поле `reference_*`	—
`edit`	Редактирует одно референсное видео. Результат сохраняет его длительность и соотношение сторон.	`reference_videos`	`duration`; `aspect_ratio` (либо передайте `adaptive`)
`extend`	Продолжает одно референсное видео с сохранением его соотношения сторон. `duration` задаёт полную длительность вместе с исходным роликом.	`reference_videos`	`aspect_ratio` (либо передайте `adaptive`)

После создания задача всё ещё может завершиться с bad_request и возвратом средств: если исходное видео для редактирования короче 4 или длиннее 30 секунд либо модель поняла промпт как другой тип задачи. Сообщение объясняет, что изменить: значение task_type или формулировку промпта.

Как написать промпт для каждого типа задачи

Что нужно получить	Что передать	Как сформулировать промпт
Новое видео по референсам	`task_type: "reference"`	Опишите новый план и назначение каждого референса. Избегайте слов «заменить», «удалить», «продлить» и «продолжить».
Изменить видео	`task_type: "edit"`	Укажите, что добавить, удалить или заменить и что должно остаться без изменений.
Продолжить видео	`task_type: "extend"`	Опишите дальнейшее действие и задайте полную длительность в `duration`.

Параметры, которые модель не принимает

Эти параметры не игнорируются, а отклоняются до списания средств:

watermark, quality, sound, multi_shots или character_orientation → field "watermark" is not supported by model seedance-2.5 (с именем переданного поля).
Имя, не используемое ни одной видеомоделью BeatAPI → unknown field: <name>.
duration: -1 (выбор длительности моделью) → "duration" is outside its supported range. Передайте целое число секунд.

Примеры запросов

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Видео по тексту

Горизонтальный ролик длительностью 5 секунд в 720p со звуком.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

Первый и последний кадры

Видео переходит от первого изображения ко второму.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "The camera pushes in from the bottle on the table to the singer on a neon stage in one continuous move",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 6,
  "resolution": "720p"
}'

Референсные изображение и аудио

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

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "The singer from the first reference image performs on stage in time with the reference music, warm spotlights, slow orbiting camera",
  "reference_images": [
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "resolution": "720p",
  "task_type": "reference"
}'

Референсные изображение, видео и аудио

Замените ссылку на видео собственным MP4 или MOV. Каждая секунда референсного видео оплачивается (см. раздел об оплате).

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "A product film: the bottle from the first reference image on a turntable, camera movement like the first reference video, cut to the beat of the reference music",
  "reference_images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "resolution": "720p",
  "task_type": "reference"
}'

Редактирование видео

Замените ссылку собственным MP4 или MOV длительностью 4–30 секунд. Не передавайте duration и aspect_ratio: результат сохраняет длительность и соотношение сторон исходного видео.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "Change the jacket of the person in the first reference video to bright red; keep everything else the same",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p",
  "task_type": "edit",
  "output_format": "mov"
}'

Продление видео

Замените ссылку своим роликом. Для исходного видео длиной 5 секунд duration: 10 добавит ещё пять секунд.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "seedance-2.5",
  "prompt": "The car keeps driving along the coast road as the sun sets, the camera rises to a wide aerial view",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "duration": 10,
  "resolution": "720p",
  "task_type": "extend"
}'

Ответы

Создание задачи (201)

Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2.5",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2.5",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 1.148671,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 1.148671,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поле	Тип	Описание
`data.id`	`string`	ID задачи: префикс `task_` и 32 буквы или цифры. Используется для опроса и сопоставления событий вебхука.
`data.object`	`string`	Всегда `task`.
`data.task_kind`	`string`	`image` или `video`.
`data.capability_id`	`string`	ID модели из вашего запроса.
`data.capability_version`	`integer`	Версия контракта модели, сейчас `1`.
`data.media_type`	`string`	`image` или `video`.
`data.model`	`string`	ID модели из запроса, совпадает с `capability_id`.
`data.status`	`string`	`queued`, `processing`, `succeeded` или `failed`. Только последние два состояния являются конечными.
`data.stage`	`string`	Повторяет `status`; сохранено для совместимости со старыми клиентами.
`data.created_at`	`integer`	Время создания задачи, в секундах Unix.
`data.updated_at`	`integer`	Время последнего изменения, в секундах Unix.
`data.completed_at`	`integer \| null`	Время завершения, в секундах Unix. Во время выполнения равно `null`.
`data.poll_after_seconds`	`integer`	Во время выполнения: сколько секунд ждать перед следующей проверкой (5 для изображений, 8 для видео).
`data.typical_seconds`	`object`	Во время выполнения, при достаточном числе недавних задач: время завершения `p50` и `p90` в секундах за последний период `window`, рассчитанное по `samples` задачам.
`data.output`	`object \| null`	Результат. Равно `null`, пока `status` не станет `succeeded`. Поля результата описаны ниже.
`data.usage.credits_reserved`	`number`	Сумма USD, зарезервированная на балансе при создании задачи.
`data.usage.credits_charged`	`number`	Стоимость задачи в USD; `0`, если задача завершилась ошибкой.
`data.usage.credits_settled`	`number`	Окончательно списанная сумма USD. Устанавливается после успешного завершения, иначе `0`.
`data.usage.credits_refunded`	`number`	Сумма USD, возвращённая на баланс. После регистрации возврата по неудачной задаче равна зарезервированной сумме.
`data.usage.billable_duration_seconds`	`integer`	Только для видео: длительность в секундах, по которой рассчитана цена. Отсутствует, если модель не сообщает длительность.
`data.request_id`	`string`	ID запроса. Укажите его при обращении в поддержку.
`data.error_code`	`string \| null`	Код ошибки; `null`, если задача не завершилась ошибкой.
`data.error_message`	`string \| null`	Описание проблемы и способа её исправить; `null`, если задача не завершилась ошибкой.

Успешно завершённая задача

GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2.5",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2.5",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 1.148671,
      "credits_settled": 1.148671,
      "credits_refunded": 0,
      "credits_charged": 1.148671,
      "billable_duration_seconds": 5
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Поля результата

Поле	Тип	Описание
`output.media`	`object[]`	Созданные файлы. Для этой модели — одно видео.
`output.media[].type`	`string`	Всегда `video`.
`output.media[].url`	`string`	HTTPS-ссылка на сохранённое видео. Скачайте его и храните у себя: срок доступности ссылки не гарантируется.
`output.media[].mime_type`	`string`	`video/mp4` либо `video/quicktime` при `output_format: "mov"`.
`output.r2_url`	`string`	Повтор ссылки на видео для старых клиентов. Вместо этого используйте `media`.

Задача, завершившаяся ошибкой

Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "seedance-2.5",
    "capability_version": 1,
    "media_type": "video",
    "model": "seedance-2.5",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 1.148671,
      "credits_settled": 0,
      "credits_refunded": 1.148671,
      "credits_charged": 0,
      "billable_duration_seconds": 5
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Поле	Тип	Описание
`data.error_code`	`string`	`bad_request` или `content_policy_violation` означают, что запрос нужно изменить. При `processing_unavailable`, `processing_timeout`, `processing_failed` или `result_transfer_failed` можно повторить позже. См. ошибки.
`data.error_message`	`string`	Сообщение с причиной ошибки и рекомендацией по исправлению.
`data.retryable`	`boolean`	Присутствует только у неудачной задачи. Значение `true` означает, что повтор того же запроса может завершиться успешно.
`data.usage`	`object`	После регистрации возврата (обычно сразу при ошибке): `credits_charged` и `credits_settled` равны `0`, а `credits_refunded` равно `credits_reserved`.

Полный пример

Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "seedance-2.5",
  "prompt": "A slow tracking shot through a rain-lit night market, neon reflections on wet stone, ambient crowd sound",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Оплата

Цена зависит от разрешения, размеров кадра и длительности видео: больше секунд, более высокое разрешение или больший кадр стоят дороже. Звук и output_format на цену не влияют; референсные изображения и аудио не добавляют стоимости.
Без референсного видео ролик 16:9 стоит примерно $0.106 (480p),$ 0.228 (720p) или $0.564 (1080p) за секунду. При другом соотношении сторон цена отличается на несколько процентов.
При передаче reference_videos ко всему запросу применяется более низкий тариф «с входным видео». Каждая секунда референсного видео учитывается наравне с секундой результата: при 16:9 примерно $0.064 (480p),$ 0.137 (720p) или $0.337 (1080p) за секунду суммарной длительности результата и референсов.
В таблице ниже указана цена 8-секундных роликов. Строки «с входным видео» также включают референсное видео длиной 8 секунд.
При редактировании исходное видео оплачивается дважды: как референс и как результат, сохраняющий исходную длительность с округлением вверх до целой секунды. usage.billable_duration_seconds показывает длительность результата.
Цена резервируется при создании задачи. Для adaptive или заданных кадров резерв рассчитывается для наибольшего кадра выбранного разрешения. Списывается резерв либо фактическая стоимость, если созданное видео оказалось дороже.
Для очень короткого референсного видео может применяться минимальная оплачиваемая длительность. Тогда итоговое списание может превысить резерв. Фактическая сумма указана в usage завершённой задачи.
Если задача завершилась ошибкой, в том числе из-за модерации после отправки, средства возвращаются полностью.

Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.

Вариант	Базовая цена (USD)
8 с · 480p · без входного видео	$0.851963
8 с · 480p · с входным видео	$1.019707
8 с · 720p · без входного видео	$1.832178
8 с · 720p · с входным видео	$2.192918
8 с · 1080p · без входного видео	$4.534641
8 с · 1080p · с входным видео	$5.403976

Частые ошибки

Ошибка или признак проблемы	Причина	Что делать
400 `resolution "1080p" is not available for this model right now; available: …`	Сейчас ни один доступный маршрут этой модели не принимает это значение. Такое возможно и для `aspect_ratio`.	Используйте значение из списка либо повторите позже.
400 `field "watermark" is not supported by model seedance-2.5`	Параметр не поддерживается этой моделью; это также относится к `quality` и `sound`.	Удалите этот параметр.
400 `"resolution" must be one of: [480p 720p 1080p]`	Передано `4k`, `2k` или значение с заглавной буквой, например `720P`.	Передайте `480p`, `720p` или `1080p`. Для 4K используйте `seedance-2`.
400 `"duration" is outside its supported range`	Передано нецелое число, число вне диапазона либо строка вместо числа.	Передайте целое число, например `5`.
400 `Cannot combine "images" with reference inputs in one task`	В одном запросе переданы кадры и `reference_*`.	Используйте либо кадры, либо референсы. Если изображений несколько, поместите их все в `reference_images`.
400 `task_type "edit" keeps the reference video's length: leave "duration" out`	В запросе редактирования передан `duration`.	Удалите `duration`.
400 `A reference video could not be read: reference_videos[0]: …`	Файл не в MP4 или MOV, сервер не поддерживает запросы диапазона байтов, возвращается 404 либо файл пустой.	Разместите ролик в общедоступном HTTPS-хранилище с поддержкой запросов диапазона байтов либо загрузите через `POST /v1/files`.
400 `The reference videos run 35 seconds in total; this model takes at most 30.`	Суммарная длительность референсных роликов превышена.	Обрежьте ролики или удалите часть из них.
Задача `failed` с `bad_request`: «Seedance read the prompt as an edit of the reference video …»	При `auto` промпт выглядит как просьба отредактировать видео. Длительность передаётся всегда, по умолчанию 5 секунд, тогда как редактирование сохраняет длину исходного ролика.	Передайте `task_type: "edit"` без `duration` и `aspect_ratio` либо `task_type: "reference"` с промптом, описывающим новый план.
Задача `failed` с `bad_request`: «For task_type “edit”, the video being edited must be 4 to 30 seconds long …»	Исходное видео для редактирования короче 4 или длиннее 30 секунд.	Обрежьте или замените исходное видео. За неудачную задачу средства возвращены.
Задача `failed` с `content_policy_violation`	Промпт, входной материал или результат отклонены модерацией, например из-за реальных людей, публичных персон или защищённых авторским правом персонажей. Материал с реальным человеком может быть отклонён; предварительно одобрить лицо нельзя.	Измените входные данные. Повтор без изменений снова завершится ошибкой; средства не списаны.
402 `insufficient_credits`	Баланс меньше необходимого резерва. Длинные референсные видео и `adaptive` увеличивают резерв.	Пополните баланс, сократите референсные видео либо задайте фиксированное `aspect_ratio`.

Краткий справочник HTTP-ошибок

Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}

HTTP-статус	`error.code`	Что делать
400	`bad_request`, `content_policy_violation`	Исправьте запрос: поле указано в сообщении. Не повторяйте запрос без изменений.
401	`missing_api_key`, `invalid_api_key` (старые клиенты могут показывать `unauthorized`)	Передайте действующий ключ в `Authorization: Bearer <key>`.
402	`insufficient_credits`	Пополните баланс или увеличьте лимит ключа, затем повторите запрос.
403	`forbidden`	Модель недоступна для ключа или аккаунта; например, бонус можно использовать только с некоторыми моделями. Не повторяйте запрос без изменений.
404	`not_found`	Для `GET /v1/tasks/{task_id}`: у аккаунта этого ключа нет такой задачи. Проверьте ID.
409	`idempotency_conflict`	Используйте новый `Idempotency-Key` или дождитесь завершения первого запроса с этим ключом.
429	`rate_limit_exceeded`	Подождите число секунд из `Retry-After` (оно также указано в `error.retry_after_seconds`), затем повторите запрос.
500	`internal_error`	Повторите запрос с увеличивающейся задержкой. Если ошибка сохраняется, обратитесь в поддержку и укажите `request_id`.
503	`processing_unavailable`, `processing_timeout`, `processing_failed`, `result_transfer_failed`	Средства не списаны. Повторите запрос с экспоненциальным увеличением задержки.

Отличия от Seedance 2.0

	Seedance 2.5	Seedance 2.0, 2.0 Fast, 2.0 Mini
Максимальная длительность	30 с	15 с
Набор референсов	До 30 изображений, 10 видео, 10 аудиофрагментов	До 9 изображений, 3 видео, 3 аудиофрагментов
Длительность референсных видео	По 2–30 с, суммарно до 30 с	По 1.8–15 с, суммарно до 15 с
Только аудио в качестве референса	Допускается	Не допускается: нужен хотя бы один референс — изображение или видео
`task_type` (edit, extend)	Да	Нет
`output_format` (MOV)	Да	Нет (MP4)
`seed`	Да	Нет
4K	Нет	Только `seedance-2`

Аутентификация

AuthorizationBearer

Передавайте API-ключ в виде Authorization: Bearer <BEATAPI_API_KEY>.

Заголовки

Idempotency-KeystringОпциональный<=255 characters

Запрос

This endpoint expects an object.

modelenumОбязательный

Модель, которую нужно вызвать.

Значение: seedance-2.5

Если значение неверно

Поле отсутствует: "model" is required
На этот адрес API отправлена модель изображений: "model" nano-banana-2 is served by POST /v1/images/tasks, not this endpoint

Допустимые значения:

promptstringОбязательный1-5000 characters

Длина: 1–5000 символов

Длина измеряется в символах. Иероглиф CJK считается одним символом.
Ссылайтесь на материалы по их порядку, например «первое референсное изображение» или «второе референсное видео».
Когда создаёте новое видео по видеореференсам, избегайте слов вроде «заменить», «удалить» или «продлить»: модель может понять их как команду редактирования. Чтобы явно задать режим, передайте task_type: "reference". Для edit опишите, что изменить и что сохранить. Для extend — что должно произойти дальше.

Если значение неверно

Поле отсутствует: "prompt" is required
Пустое значение или превышена допустимая длина: "prompt" has an unsupported length

aspect_ratioenumОпциональныйПо умолчанию adaptive

Соотношение ширины и высоты видео. Значение adaptive позволяет модели определить его по входным материалам.

Допустимые значения: adaptive, 21:9, 16:9, 4:3, 1:1, 3:4, 9:16

По умолчанию: adaptive

Игнорируется, если в images передан первый кадр: видео сохраняет соотношение сторон этого кадра.
При task_type со значением edit или extend не передавайте параметр либо укажите adaptive: результат сохраняет соотношение сторон исходного видео.
При adaptive или заданных кадрах сумма резерва рассчитывается для наибольшего кадра выбранного разрешения, поэтому может быть немного выше, чем при фиксированном соотношении сторон.

Если значение неверно

Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [adaptive 21:9 16:9 4:3 1:1 3:4 9:16]
Фиксированное соотношение сторон при edit или extend: task_type "edit" keeps the reference video's aspect ratio: leave "aspect_ratio" out or send "adaptive"

durationintegerОпциональный4-30По умолчанию 5

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

По умолчанию: 5

Диапазон: 4–30

Если параметр не указан, передаётся 5, в том числе при task_type со значением auto или reference.
При task_type: "extend" всегда задавайте длительность: это полная длина результата вместе с исходным видео. Чтобы добавить 5 секунд к 5-секундному ролику, передайте 10. Если не указать параметр, будет запрошено всего 5 секунд.
При task_type: "edit" не передавайте длительность: результат сохраняет длину исходного видео.

Если значение неверно

Значение вне диапазона или не является целым числом: "duration" is outside its supported range
Передано при task_type: "edit": task_type "edit" keeps the reference video's length: leave "duration" out

generate_audiobooleanОпциональныйПо умолчанию true

Нужно ли генерировать звуковую дорожку. На цену это не влияет.

По умолчанию: true

Если значение неверно

Значение не равно true или false: "generate_audio" must be a boolean

imageslist of stringsОпциональный

Первый кадр либо первый и последний кадры.

Число элементов: 1–2

Каждый элемент — общедоступная ссылка https://. Если файл находится на вашем устройстве, сначала загрузите его через POST /v1/files, затем передайте полученный data.url.

Одна ссылка: видео начинается с этого изображения. Две ссылки: images[0] задаёт первый кадр, images[1] — последний.
Видео сохраняет соотношение сторон первого изображения; aspect_ratio не применяется.
Если изображений больше или они должны направлять генерацию, но не служить кадрами, используйте reference_images.

Если значение неверно

Больше двух ссылок: "images" accepts at most 2 items
Передано вместе с любым полем reference_*: Cannot combine "images" with reference inputs in one task
Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL

output_formatenumОпциональный

Контейнер результата: mp4 по умолчанию или mov. Цена одинакова.

Допустимые значения: mp4, mov

mov удобен для последующего монтажа, но доступен не всегда. Если формат недоступен, запрос отклоняется до списания средств; сообщение перечисляет доступные сейчас форматы.

Если значение неверно

Значение отсутствует в списке допустимых: "output_format" must be one of: [mp4 mov]

Допустимые значения:

reference_audioslist of stringsОпциональный

Число элементов: 1–10

Для WAV и MP3 проверяются перечисленные ниже ограничения длительности. Другие форматы передаются модели без измерения.

Если значение неверно

Превышено максимальное число элементов: "reference_audios" accepts at most 10 items

reference_imageslist of stringsОпциональный

Изображения, определяющие содержание, персонажей, товары или стиль видео.

Число элементов: 1–30

Изображения используются в порядке списка. В промпте ссылайтесь на них по порядку.

Если значение неверно

Превышено максимальное число элементов: "reference_images" accepts at most 30 items
Передано вместе с images: Cannot combine "images" with reference inputs in one task

reference_videoslist of stringsОпциональный

Число элементов: 1–10

Каждая ссылка должна возвращать MP4- или MOV-файл с сервера, поддерживающего запросы диапазона байтов. Шлюз измеряет длительность каждого ролика до создания задачи, поскольку секунды референсных видео оплачиваются.
Обязательно при task_type со значением edit или extend.

Примечания: Каждая секунда референсного видео увеличивает стоимость (см. раздел об оплате). Обрежьте ролик до нужного фрагмента.

Если значение неверно

Превышено максимальное число элементов: "reference_videos" accepts at most 10 items
Не удалось прочитать ролик: A reference video could not be read: reference_videos[0]: its host does not allow byte-range requests. Send an MP4 or MOV file at a public HTTPS URL whose host allows byte-range requests.

resolutionenumОпциональныйПо умолчанию 720p

Разрешение результата. Чем оно выше, тем дороже секунда видео.

Допустимые значения: 480p, 720p, 1080p

По умолчанию: 720p

Используйте только строчные буквы. Seedance 2.5 не поддерживает 4K; для этого используйте seedance-2.

Если значение неверно

Недопустимое значение, например 4k или 720P: "resolution" must be one of: [480p 720p 1080p]

Допустимые значения:

seedintegerОпциональный-1-4294967295

Диапазон: -1–4294967295

Одинаковый seed при одинаковом запросе даёт похожие результаты, но полное совпадение не гарантируется.

Если значение неверно

Значение вне диапазона: "seed" is outside its supported range

task_typeenumОпциональный

Допустимые значения: auto, reference, edit, extend

Явное указание типа задачи позволяет шлюзу проверить запрос до списания средств. Правила каждого типа приведены ниже в разделе «Типы задач».
При auto или reference длительность передаётся всегда: 5, если вы не указали другую. Поэтому промпт, который модель поняла как редактирование, может вызвать ошибку после отправки с возвратом средств либо повторную обработку в режиме редактирования с оплатой по длительности исходного видео. Если нужно редактирование, передавайте edit.

Если значение неверно

Значение отсутствует в списке допустимых: "task_type" must be one of: [auto reference edit extend]
edit или extend без референсного видео: task_type "edit" needs a video in "reference_videos"
reference без референсных материалов: task_type "reference" needs reference inputs

Допустимые значения:

Ответ

Ошибки

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

409

Conflict Error

429

Too Many Requests Error

500

Internal Server Error

503

Service Unavailable Error

Идентификаторы моделей

Адрес API и авторизация

Authorization string Обязательно

Как выполняется запрос

Создайте задачу

Дождитесь завершения

Сохраните результат

Режимы ввода

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

model string Обязательно

prompt string Обязательно

images string[] Необязательно

reference_images string[] Необязательно

reference_videos string[] Необязательно

reference_audios string[] Необязательно

duration integer НеобязательноПо умолчанию: 5

aspect_ratio string НеобязательноПо умолчанию: adaptive

resolution string НеобязательноПо умолчанию: 720p

generate_audio boolean НеобязательноПо умолчанию: true

seed integer Необязательно

task_type string Необязательно

output_format string Необязательно

Ограничения входных материалов

Типы задач

Как написать промпт для каждого типа задачи

Параметры, которые модель не принимает

Примеры запросов

Видео по тексту

Первый и последний кадры

Референсные изображение и аудио

Референсные изображение, видео и аудио

Редактирование видео

Продление видео

Ответы

Создание задачи (201)

Успешно завершённая задача

Поля результата

Задача, завершившаяся ошибкой

Полный пример

Оплата

Частые ошибки

Краткий справочник HTTP-ошибок

Отличия от Seedance 2.0

Аутентификация

Заголовки

Запрос

Ответ

Ошибки

`Authorization` string Обязательно

`model` string Обязательно

`prompt` string Обязательно

`images` string[] Необязательно

`reference_images` string[] Необязательно

`reference_videos` string[] Необязательно

`reference_audios` string[] Необязательно

`duration` integer НеобязательноПо умолчанию: `5`

`aspect_ratio` string НеобязательноПо умолчанию: `adaptive`

`resolution` string НеобязательноПо умолчанию: `720p`

`generate_audio` boolean НеобязательноПо умолчанию: `true`

`seed` integer Необязательно

`task_type` string Необязательно

`output_format` string Необязательно