Kling 4.0 | BeatAPI API Documentation

Создавайте видео длительностью 3–30 секунд в 720p или 1080p со сгенерированным звуком: по тексту, кадрам в хронологическом порядке либо референсным изображениям, видео, голосам и именованным элементам. Оплата посекундная.

Асинхронная обработка: запрос создания возвращает ID задачи. Видео будет доступно после её успешного завершения.
Четыре варианта ввода: только текст; кадры (images в хронологическом порядке); референсные изображения, видео и голоса; до семи именованных elements. Кадры нельзя сочетать с референсами или элементами.
Укажите каждый материал в промпте: @image_1, @video_1, @voice_1, @ с именем элемента, @first_frame, @keyframe_1, @last_frame. Каждое упоминание @ должно соответствовать материалу того же запроса.
Звук генерируется всегда. keep_original_sound позволяет вместо него сохранить собственный звук референсных видео.
duration — от 3 до 30 секунд (по умолчанию 5), разрешение — 720p по умолчанию либо 1080p. Оплата посекундная по тарифу выбранного разрешения. Задача, завершившаяся ошибкой, не оплачивается.

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

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

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

Две модели генерации Kling используют один адрес API. Значения ниже взяты непосредственно из контракта шлюза. Только Kling 4.0 принимает референсы, больше двух кадров и до семи элементов.

ID модели	`duration` (с)	`resolution`	Максимум кадров	Максимум референсных изображений	Максимум элементов	Когда выбрать
`kling-v4`	3–30	`720p`, `1080p`	10	10	7	Нужны видео до 30 секунд, референсные изображения, видео или голоса, промежуточные кадры либо больше трёх элементов.
`kling-v3`	3–15	`std`, `pro`	2	—	3	Нужны многосценные раскадровки, видео без звука либо более низкая цена за секунду.

Адрес 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`	Не передавайте материалы. Без `aspect_ratio` видео будет в 16:9.
Первый кадр	`model`, `prompt`, `images` (1 ссылка)	Видео начинается с изображения и сохраняет его соотношение сторон.
Первый и последний кадры	`model`, `prompt`, `images` (2 ссылки)	`images[0]` — первый кадр, `images[1]` — последний.
Кадры	`model`, `prompt`, `images` (от 3 до 10 ссылок)	Первый, промежуточные и последний кадры в хронологическом порядке. Число изображений не должно превышать длительность видео в секундах более чем на одно.
Референсы и элементы	`model`, `prompt` и любые из полей `reference_images`, `reference_videos`, `reference_audios`, `elements`	Любое сочетание в пределах ограничений ниже. Нельзя сочетать с `images`. Назовите каждый материал в промпте.

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

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

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

Значение: kling-v4

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

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

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

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

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

Длина измеряется в символах. Иероглиф CJK считается одним символом.
Упоминания: reference_images обозначаются как @image_1, @image_2 …, reference_videos — как @video_1 …, reference_audios — как @voice_1 …, элемент — как @ с его name. Кадры обозначаются @first_frame, @keyframe_1, @keyframe_2 … и @last_frame.
Каждое упоминание @ должно соответствовать материалу того же запроса. Упоминание номера или кадра без соответствующего материала, например @image_3 при двух референсных изображениях или @last_frame при одном изображении, отклоняется при создании задачи.

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

Поле отсутствует: "prompt" is required
Пустое значение или превышена допустимая длина: "prompt" has an unsupported length
Упомянут материал, отсутствующий в запросе: the prompt names @image_3, which this request does not send

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

Кадры в хронологическом порядке: одна ссылка задаёт первый кадр, две — первый и последний, большее число добавляет промежуточные кадры между ними.

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

При трёх и более ссылках images[0] — первый кадр, последняя ссылка — последний. Ссылки между ними — промежуточные кадры: images[1] соответствует @keyframe_1, images[2] — @keyframe_2 и так далее.
Число изображений не должно превышать длительность видео в секундах более чем на одно (duration + 1; без duration считается 5 секунд). Во всех случаях — не более 10 изображений.
Кадры нельзя передавать вместе с reference_images, reference_videos, reference_audios, elements или aspect_ratio: видео сохраняет соотношение сторон первого кадра.

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

Больше 10 ссылок: "images" accepts at most 10 items
Число ссылок больше duration + 1, здесь 7 ссылок для 5-секундного видео: Kling V4 takes at most 6 images for a 5-second video
Передано вместе с любым полем reference_*: Cannot combine "images" with reference inputs in one task
Передано вместе с elements: Kling V4 cannot combine elements with images
Передано вместе с aspect_ratio: Kling V4 takes the first frame's shape; do not send aspect_ratio with images
Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL

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

Изображения, определяющие содержание, персонажей, товары или стиль видео. Назовите их в промпте как @image_1, @image_2 … в порядке списка.

Нельзя сочетать с images.
Учитываются в общем лимите 15 референсов и элементов.

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

Превышено максимальное число элементов: "reference_images" accepts at most 10 items
Суммарно больше 15 референсов и элементов: Kling V4 takes at most 15 reference inputs and elements together

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

Видео, из которых нужно взять движение, работу камеры или содержание. Назовите их в промпте как @video_1, @video_2 … в порядке списка.

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

Каждый ролик — от 2 до 30 секунд; общая длительность — не более 30 секунд. До создания задачи шлюз измеряет каждый ролик и отклоняет нарушающий ограничения, указав его в сообщении.
Референсных видео и видеоэлементов суммарно не более 5; они также учитываются в общем лимите 15 референсов и элементов.
Результат содержит сгенерированный звук, если не передать keep_original_sound: true для сохранения звука референсных видео.

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

Превышено максимальное число элементов: "reference_videos" accepts at most 5 items
Ролик короче 2 или длиннее 30 секунд: reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.
Общая длительность роликов больше 30 секунд: The reference videos run 36 seconds in total; this model takes at most 30.
Суммарно больше 5 референсных видео и видеоэлементов: Kling V4 takes at most 5 reference videos and video elements together

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

Голоса для видео. Назовите их в промпте как @voice_1, @voice_2 … в порядке списка.

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

Нельзя сочетать с images.
Учитываются в общем лимите 15 референсов и элементов.

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

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

`elements` object[] Необязательно

До семи именованных объектов: персонаж, животное, предмет, костюм, сцена или эффект. Каждый задаётся один раз и упоминается в промпте как @ с его name.

Число элементов: ≤ 7

Массив из не более семи объектов. Каждый объект принимает только следующие поля:
elements[].name (string, обязательно): от 1 до 20 букв, цифр, подчёркиваний или китайских иероглифов; имя уникально в запросе без учёта регистра. Запрещены image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame.
elements[].element_input_urls (массив строк): 2–4 общедоступные HTTPS-ссылки на изображения элемента; первое — основной вид.
elements[].element_input_video_urls (массив строк): ровно одна общедоступная HTTPS-ссылка на одноплановое видео персонажа длиной 3–8 секунд. Передайте это поле либо element_input_urls, но не оба.
elements[].element_input_audio_urls (массив строк, необязательно): ровно одна общедоступная HTTPS-ссылка на аудио — голос персонажа.
elements[].tag (string, необязательно): тип элемента. Видеоэлемент или элемент с голосом должен быть персонажем: не передавайте tag либо укажите character.
elements[].description (string, необязательно): описание элемента, не более 100 символов.
Видеоэлементов — не более 3; вместе с reference_videos — не более 5. Каждый элемент учитывается в общем лимите 15 референсов и элементов.
Элементы нельзя передавать вместе с images.

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

Больше семи элементов: "elements" accepts at most 7 items
Элемент не является объектом: "elements[0]" must be an object
У элемента нет name: "name" is required in "elements[0]"
name пустое или длиннее 20 символов: "elements[0].name" has an unsupported length
name содержит недопустимые символы или является зарезервированным именем: elements[0].name "image_1" is not a name Kling V4 accepts
Одно name повторяется без учёта регистра: elements[1].name "Hero" is used twice
Переданы и изображения, и видео, либо ни то ни другое: elements[0] takes either element_input_urls or element_input_video_urls
Меньше двух изображений: "elements[0].element_input_urls" requires at least 2 item
Больше четырёх изображений: "elements[0].element_input_urls" accepts at most 4 items
У видеоэлемента tag не равно character: elements[0] is a video element, which is always a character
Голос передан для элемента, у которого tag не равно character: elements[0] has a voice, which only a character element takes
tag отсутствует в списке допустимых значений: "elements[0].tag" must be one of: [character animal prop costume scene effect others]
description длиннее 100 символов: "elements[0].description" has an unsupported length
Поле, которое элемент не принимает: field "start_time" is not supported in "elements[0]"
Больше трёх видеоэлементов: Kling V4 takes at most 3 video elements
Передано вместе с images: Kling V4 cannot combine elements with images

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

Длительность видео в секундах, целое число. Именно эта длительность оплачивается.

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

Если параметр не указан, используется и оплачивается 5.
При передаче кадров параметр также ограничивает число изображений: не более duration + 1 и во всех случаях не более 10.

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

Число вне диапазона, нецелое число либо строка вместо числа: "duration" is outside its supported range

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

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

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

Если параметр не указан, используется 16:9.
Не передавайте вместе с images: видео сохраняет соотношение сторон первого кадра.

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

Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [16:9 9:16 1:1 21:9]
Передано вместе с images: Kling V4 takes the first frame's shape; do not send aspect_ratio with images

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

Разрешение результата. Секунда в 1080p стоит дороже, чем в 720p.

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

Если параметр не указан, используется и оплачивается 720p.
Эта модель не поддерживает 4K.

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

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

`keep_original_sound` boolean Необязательно

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

Допускается только с reference_videos. Без них поле отклоняется даже со значением false.
Без этого параметра видео содержит сгенерированный звук. Поля для отключения звука нет.

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

Значение не равно true или false: "keep_original_sound" must be a boolean
Передано без reference_videos: "keep_original_sound" needs reference_videos

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

images нельзя сочетать с полями референсных материалов.
images — кадры в хронологическом порядке: одно изображение задаёт первый кадр, два — первый и последний, большее число добавляет промежуточные кадры. В промпте они обозначаются @first_frame, @keyframe_1, @keyframe_2 … и @last_frame.
Число изображений не должно превышать длительность видео в секундах более чем на одно. Во всех случаях допускается не более 10 изображений.
В промпте reference_images обозначаются @image_1, @image_2 …, reference_videos — @video_1 …, reference_audios — @voice_1 …, а элементы — @ с их именем. Каждое упоминание @ должно соответствовать материалу того же запроса.
Каждое референсное видео длится 2–30 секунд, общая длительность — до 30 секунд. Референсных видео и видеоэлементов вместе не более 5, из них видеоэлементов — не более 3. Общее число reference_images, reference_videos, reference_audios и elements — не более 15.
Элемент задаётся 2–4 изображениями в element_input_urls, первое — основной вид, либо одним одноплановым видео персонажа длиной 3–8 секунд в element_input_video_urls. element_input_audio_urls задаёт голос персонажа.
Имена элементов содержат 1–20 букв, цифр, подчёркиваний или китайских иероглифов и уникальны без учёта регистра. Запрещены image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame.
elements и aspect_ratio нельзя передавать с images: результат сохраняет пропорции первого кадра. Без images значение aspect_ratio по умолчанию — 16:9.
keep_original_sound сохраняет собственный звук референсных видео и требует reference_videos. В остальных случаях видео содержит сгенерированный звук.

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

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

Материал	Ограничения, проверяемые до создания задачи
Изображения	ширина и высота: 300–65536 пикс.; соотношение сторон (ширина ÷ высота): 0.4–2.5
Видео	каждый файл: 2–30 с; суммарно не более 30 с

До создания задачи шлюз измеряет images, reference_images и reference_videos. Материал вне ограничений отклоняется с указанием списка и индекса, например reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.. Средства не списываются.
Для ссылок элементов и reference_audios до создания задачи проверяется только общедоступность HTTPS-ссылок. Видео элемента должно длиться 3–8 секунд.
Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

Упоминания в промпте

У каждого типа материала своё обозначение; нумерация начинается с 1 в порядке списка:

Упоминание	Что обозначает	Когда доступно
`@image_1`, `@image_2` …	`reference_images`	Передано как минимум столько референсных изображений
`@video_1`, `@video_2` …	`reference_videos`	Передано как минимум столько референсных видео
`@voice_1`, `@voice_2` …	`reference_audios`	Передано как минимум столько референсных аудиоссылок
`@` + имя элемента	Элемент с этим `name`	Элемент присутствует в `elements`
`@first_frame`	`images[0]`	Передано хотя бы одно изображение
`@keyframe_1`, `@keyframe_2` …	Промежуточные кадры, начиная с `images[1]`	Передано три или более изображений
`@last_frame`	Последняя ссылка в `images`	Передано два или более изображений

Упоминание номера или кадра без соответствующего материала отклоняется при создании задачи, например the prompt names @last_frame, which this request does not send.

Совместимость параметров

Эти правила проверяются при создании задачи. Нарушающий их запрос отклоняется с 400 bad_request без списания средств.

Правило	Сообщение
`images` с любым полем `reference_*`	`Cannot combine "images" with reference inputs in one task`
`images` с `elements`	`Kling V4 cannot combine elements with images`
`images` с `aspect_ratio`	`Kling V4 takes the first frame's shape; do not send aspect_ratio with images`
Изображений больше, чем `duration` + 1, здесь для 5-секундного видео	`Kling V4 takes at most 6 images for a 5-second video`
`keep_original_sound` без `reference_videos`	`"keep_original_sound" needs reference_videos`
Больше 3 видеоэлементов	`Kling V4 takes at most 3 video elements`
Суммарно больше 5 референсных видео и видеоэлементов	`Kling V4 takes at most 5 reference videos and video elements together`
Суммарно больше 15 референсных изображений, видео, аудиоссылок и элементов	`Kling V4 takes at most 15 reference inputs and elements together`

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

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

sound, generate_audio, seed, multi_shots, multi_prompt, quality, watermark, task_type, output_format → field "sound" is not supported by model kling-v4 (с именем переданного поля).
Любое другое неизвестное поле → unknown field: <name>.

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

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections, a low ambient synth tone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

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

Ролик длительностью 5 секунд в 16:9 и 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": "kling-v4",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections, a low ambient synth tone",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p"
}'

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

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

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "The camera moves from the bottle in @first_frame to the singer on a neon stage in @last_frame in one continuous shot",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "1080p"
}'

Референсные изображения и голос

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

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "The singer from @image_1 lifts the bottle from @image_2 toward the camera and says a short line in the voice of @voice_1",
  "reference_images": [
    "https://cdn.beatapi.io/samples/neon-singer.png",
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "reference_audios": [
    "https://cdn.beatapi.io/samples/neon-singer-preview.mp3"
  ],
  "duration": 8,
  "aspect_ratio": "9:16",
  "resolution": "720p"
}'

Референсное видео с собственным звуком

Замените пример своей ссылкой на ролик длиной 2–30 секунд. keep_original_sound сохраняет его звук вместо сгенерированного аудио.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-v4",
  "prompt": "Restyle @video_1 as a neon-lit night scene and keep its camera movement",
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "keep_original_sound": true,
  "duration": 10,
  "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": "kling-v4",
  "prompt": "@singer walks across a neon stage holding @bottle and smiles at the camera",
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "elements": [
    {
      "name": "singer",
      "tag": "character",
      "description": "A performer in a silver jacket",
      "element_input_urls": [
        "https://your-cdn.example.com/elements/singer-front.png",
        "https://your-cdn.example.com/elements/singer-side.png"
      ]
    },
    {
      "name": "bottle",
      "tag": "prop",
      "element_input_urls": [
        "https://your-cdn.example.com/elements/bottle-front.png",
        "https://your-cdn.example.com/elements/bottle-back.png"
      ]
    }
  ]
}'

Ответы

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

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

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v4",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v4",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.75,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.75,
      "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": "kling-v4",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v4",
    "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": 0.75,
      "credits_settled": 0.75,
      "credits_refunded": 0,
      "credits_charged": 0.75,
      "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`	MIME-тип файла, обычно `video/mp4`.
`output.r2_url`	`string`	Повтор ссылки на видео для старых клиентов. Вместо этого используйте `media`.

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

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

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v4",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v4",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.75,
      "credits_settled": 0,
      "credits_refunded": 0.75,
      "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": "kling-v4",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections, a low ambient synth tone",
  "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"])

Оплата

Цена за секунду видео: $0.15 в `720p` и$ 0.23 в 1080p. В таблице ниже указаны цены 8-секундных роликов.
Число секунд задаётся duration, либо равно 5, если параметр не указан. Оно отражено в usage.billable_duration_seconds задачи.
При входном видео — reference_videos или элементе, заданном видео, — тариф составляет $0.09 за секунду в `720p` и$ 0.14 в 1080p. Оплачивается сумма секунд результата и входных видео, но не меньше удвоенной длительности результата. Каждый видеоэлемент учитывается как 8 секунд. keep_original_sound требует reference_videos, поэтому всегда оплачивается по этому правилу. Строки с входным видео ниже показывают 8-секундный результат с 8-секундным референсом.
Каждое видео содержит звук — сгенерированный или сохранённый из референсных видео — без отдельной доплаты.
Цена резервируется при создании задачи и окончательно списывается, когда видео готово. Если задача завершилась ошибкой, в том числе из-за модерации после отправки, средства возвращаются полностью.

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

Вариант	Базовая цена (USD)
8 с · 720p	$1.2
8 с · 720p · с входным видео · 8 с референс	$1.44
8 с · 1080p	$1.84
8 с · 1080p · с входным видео · 8 с референс	$2.24

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

Ошибка или признак проблемы	Причина	Что делать
400 `the prompt names @image_3, which this request does not send`	Упоминание ссылается на отсутствующий материал, например третье референсное изображение, когда передано два.	Каждое упоминание `@` должно соответствовать материалу того же запроса; нумерация начинается с 1 в порядке списка.
400 `Cannot combine "images" with reference inputs in one task`	Кадры в `images` переданы вместе с `reference_images`, `reference_videos` или `reference_audios`.	Используйте либо кадры, либо референсы. Изображения, которые должны направлять генерацию, но не служить кадрами, передавайте в `reference_images`.
400 `Kling V4 cannot combine elements with images`	`elements` передано вместе с кадрами.	Удалите `images` либо `elements`.
400 `Kling V4 takes the first frame's shape; do not send aspect_ratio with images`	`aspect_ratio` передано вместе с кадрами.	Удалите `aspect_ratio` и обрежьте первый кадр до нужного соотношения сторон.
400 `Kling V4 takes at most 6 images for a 5-second video`	Кадров больше, чем `duration` + 1.	Передайте меньше кадров либо увеличьте `duration`. Во всех случаях допускается не более 10 кадров.
400 `elements[0] takes either element_input_urls or element_input_video_urls`	У элемента заданы и изображения, и видео, либо ни то ни другое.	Для каждого элемента задайте 2–4 изображения либо одно видео персонажа.
400 `"elements[0].element_input_urls" requires at least 2 item`	У элемента только одно изображение.	Передайте 2–4 изображения элемента, начав с основного вида.
400 `elements[0].name "image_1" is not a name Kling V4 accepts`	Имя содержит символы, отличные от букв, цифр, подчёркиваний и китайских иероглифов, либо является зарезервированным, например `image_1` или `first_frame`.	Переименуйте элемент, например в `singer` или `hero_bottle`, и используйте это имя в упоминаниях.
400 `"keep_original_sound" needs reference_videos`	`keep_original_sound` передано без `reference_videos`.	Удалите параметр либо добавьте референсные видео, звук которых нужно сохранить.
400 `reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.`	Референсный ролик короче 2 или длиннее 30 секунд. Общая длительность всех роликов также не должна превышать 30 секунд.	Обрежьте ролик до нужного фрагмента.
400 `field "sound" is not supported by model kling-v4`	Звук генерируется всегда; переключателя звука нет. `generate_audio`, `seed` и `multi_shots` также отклоняются.	Удалите параметр. Чтобы сохранить собственный звук референсного видео, передайте `keep_original_sound: true`.
400 `"resolution" must be one of: [720p 1080p]`	Передано `4K` или название уровня вроде `pro`.	Передайте `720p` или `1080p`.
400 `"duration" is outside its supported range`	Передано нецелое число, число вне диапазона 3–30 либо строка вместо числа.	Передайте целое число, например `5`.
Задача `failed` с `content_policy_violation`	Промпт, входной материал или результат отклонены модерацией.	Измените промпт или входные материалы. Повтор без изменений снова завершится ошибкой; средства не списаны.
402 `insufficient_credits`	Баланс меньше резерва для выбранных длительности и разрешения.	Пополните баланс, уменьшите `duration` либо используйте `720p`.

Краткий справочник 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`	Средства не списаны. Повторите запрос с экспоненциальным увеличением задержки.

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

AuthorizationBearer

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

Заголовки

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

Запрос

This endpoint expects an object.

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

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

Значение: kling-v4

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

Поле отсутствует: "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 считается одним символом.
Упоминания: reference_images обозначаются как @image_1, @image_2 …, reference_videos — как @video_1 …, reference_audios — как @voice_1 …, элемент — как @ с его name. Кадры обозначаются @first_frame, @keyframe_1, @keyframe_2 … и @last_frame.
Каждое упоминание @ должно соответствовать материалу того же запроса. Упоминание номера или кадра без соответствующего материала, например @image_3 при двух референсных изображениях или @last_frame при одном изображении, отклоняется при создании задачи.

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

Поле отсутствует: "prompt" is required
Пустое значение или превышена допустимая длина: "prompt" has an unsupported length
Упомянут материал, отсутствующий в запросе: the prompt names @image_3, which this request does not send

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

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

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

По умолчанию: 16:9

Если параметр не указан, используется 16:9.
Не передавайте вместе с images: видео сохраняет соотношение сторон первого кадра.

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

Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [16:9 9:16 1:1 21:9]
Передано вместе с images: Kling V4 takes the first frame's shape; do not send aspect_ratio with images

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

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

Длительность видео в секундах, целое число. Именно эта длительность оплачивается.

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

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

Если параметр не указан, используется и оплачивается 5.
При передаче кадров параметр также ограничивает число изображений: не более duration + 1 и во всех случаях не более 10.

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

Число вне диапазона, нецелое число либо строка вместо числа: "duration" is outside its supported range

elementslist of objectsОпциональный

Число элементов: ≤ 7

Массив из не более семи объектов. Каждый объект принимает только следующие поля:
elements[].name (string, обязательно): от 1 до 20 букв, цифр, подчёркиваний или китайских иероглифов; имя уникально в запросе без учёта регистра. Запрещены image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame.
elements[].element_input_urls (массив строк): 2–4 общедоступные HTTPS-ссылки на изображения элемента; первое — основной вид.
elements[].element_input_video_urls (массив строк): ровно одна общедоступная HTTPS-ссылка на одноплановое видео персонажа длиной 3–8 секунд. Передайте это поле либо element_input_urls, но не оба.
elements[].element_input_audio_urls (массив строк, необязательно): ровно одна общедоступная HTTPS-ссылка на аудио — голос персонажа.
elements[].tag (string, необязательно): тип элемента. Видеоэлемент или элемент с голосом должен быть персонажем: не передавайте tag либо укажите character.
elements[].description (string, необязательно): описание элемента, не более 100 символов.
Видеоэлементов — не более 3; вместе с reference_videos — не более 5. Каждый элемент учитывается в общем лимите 15 референсов и элементов.
Элементы нельзя передавать вместе с images.

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

Больше семи элементов: "elements" accepts at most 7 items
Элемент не является объектом: "elements[0]" must be an object
У элемента нет name: "name" is required in "elements[0]"
name пустое или длиннее 20 символов: "elements[0].name" has an unsupported length
name содержит недопустимые символы или является зарезервированным именем: elements[0].name "image_1" is not a name Kling V4 accepts
Одно name повторяется без учёта регистра: elements[1].name "Hero" is used twice
Переданы и изображения, и видео, либо ни то ни другое: elements[0] takes either element_input_urls or element_input_video_urls
Меньше двух изображений: "elements[0].element_input_urls" requires at least 2 item
Больше четырёх изображений: "elements[0].element_input_urls" accepts at most 4 items
У видеоэлемента tag не равно character: elements[0] is a video element, which is always a character
Голос передан для элемента, у которого tag не равно character: elements[0] has a voice, which only a character element takes
tag отсутствует в списке допустимых значений: "elements[0].tag" must be one of: [character animal prop costume scene effect others]
description длиннее 100 символов: "elements[0].description" has an unsupported length
Поле, которое элемент не принимает: field "start_time" is not supported in "elements[0]"
Больше трёх видеоэлементов: Kling V4 takes at most 3 video elements
Передано вместе с images: Kling V4 cannot combine elements with images

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

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

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

При трёх и более ссылках images[0] — первый кадр, последняя ссылка — последний. Ссылки между ними — промежуточные кадры: images[1] соответствует @keyframe_1, images[2] — @keyframe_2 и так далее.
Число изображений не должно превышать длительность видео в секундах более чем на одно (duration + 1; без duration считается 5 секунд). Во всех случаях — не более 10 изображений.
Кадры нельзя передавать вместе с reference_images, reference_videos, reference_audios, elements или aspect_ratio: видео сохраняет соотношение сторон первого кадра.

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

Больше 10 ссылок: "images" accepts at most 10 items
Число ссылок больше duration + 1, здесь 7 ссылок для 5-секундного видео: Kling V4 takes at most 6 images for a 5-second video
Передано вместе с любым полем reference_*: Cannot combine "images" with reference inputs in one task
Передано вместе с elements: Kling V4 cannot combine elements with images
Передано вместе с aspect_ratio: Kling V4 takes the first frame's shape; do not send aspect_ratio with images
Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL

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

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

Допускается только с reference_videos. Без них поле отклоняется даже со значением false.
Без этого параметра видео содержит сгенерированный звук. Поля для отключения звука нет.

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

Значение не равно true или false: "keep_original_sound" must be a boolean
Передано без reference_videos: "keep_original_sound" needs reference_videos

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

Голоса для видео. Назовите их в промпте как @voice_1, @voice_2 … в порядке списка.

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

Нельзя сочетать с images.
Учитываются в общем лимите 15 референсов и элементов.

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

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

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

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

Нельзя сочетать с images.
Учитываются в общем лимите 15 референсов и элементов.

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

Превышено максимальное число элементов: "reference_images" accepts at most 10 items
Суммарно больше 15 референсов и элементов: Kling V4 takes at most 15 reference inputs and elements together

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

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

Каждый ролик — от 2 до 30 секунд; общая длительность — не более 30 секунд. До создания задачи шлюз измеряет каждый ролик и отклоняет нарушающий ограничения, указав его в сообщении.
Референсных видео и видеоэлементов суммарно не более 5; они также учитываются в общем лимите 15 референсов и элементов.
Результат содержит сгенерированный звук, если не передать keep_original_sound: true для сохранения звука референсных видео.

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

Превышено максимальное число элементов: "reference_videos" accepts at most 5 items
Ролик короче 2 или длиннее 30 секунд: reference_videos[0] is 35 seconds long; this model takes reference video of 2 to 30 seconds.
Общая длительность роликов больше 30 секунд: The reference videos run 36 seconds in total; this model takes at most 30.
Суммарно больше 5 референсных видео и видеоэлементов: Kling V4 takes at most 5 reference videos and video elements together

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

Разрешение результата. Секунда в 1080p стоит дороже, чем в 720p.

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

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

Если параметр не указан, используется и оплачивается 720p.
Эта модель не поддерживает 4K.

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

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

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

Ответ

Ошибки

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[] Необязательно

elements object[] Необязательно

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

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

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

keep_original_sound boolean Необязательно

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

Упоминания в промпте

Совместимость параметров

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

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

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

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

Референсные изображения и голос

Референсное видео с собственным звуком

Именованные элементы

Ответы

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

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

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

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

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

Оплата

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

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

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

Заголовки

Запрос

Ответ

Ошибки

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

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

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

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

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

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

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

`elements` object[] Необязательно

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

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

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

`keep_original_sound` boolean Необязательно