Kling 3.0 | BeatAPI API Documentation

Создавайте видео длительностью 3–15 секунд на уровне std или pro по тексту либо одному-двум кадрам, с многосценной раскадровкой и повторно используемыми элементами. Оплата посекундная.

Асинхронная обработка: запрос создания возвращает ID задачи. Видео будет доступно после её успешного завершения.
Три варианта ввода: только текст, первый кадр либо первый и последний кадры. Модель не принимает референсные изображения, видео или аудио.
resolution задаёт уровень: std генерирует в 720p, pro по умолчанию — в 1080p.
Многосценный режим: до пяти сцен с собственными промптами и длительностью по одному первому кадру. Сумма длительностей сцен должна равняться duration.
Элементы: до трёх именованных объектов, которые один раз задаются через elements.
Оплата за секунду видео по тарифу выбранного уровня. Задача, завершившаяся ошибкой, не оплачивается.

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

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

Адрес 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`	Не передавайте `images`.
Первый кадр	`model`, `prompt`, `images` (1 ссылка)	Видео начинается с переданного изображения.
Первый и последний кадры	`model`, `prompt`, `images` (2 ссылки)	`images[0]` — первый кадр, `images[1]` — последний.
Многосценный режим	`model`, `prompt`, `images` (ровно 1 ссылка), `multi_shots: true`, `multi_prompt`	Сумма длительностей сцен должна равняться `duration`, либо 5, если параметр не указан.
Элементы	`model`, `prompt`, `elements`	Можно сочетать с любым режимом выше. Не более трёх элементов.

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

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

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

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

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

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

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

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

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

Длина измеряется в символах. Иероглиф CJK считается одним символом.
Обязателен во всех режимах, включая многосценный, где у каждой сцены также есть свой промпт в multi_prompt.

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

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

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

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

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

Одна ссылка: видео начинается с этого изображения. Две ссылки: images[0] задаёт первый кадр, images[1] — последний.
Многосценный режим (multi_shots: true) принимает ровно одно изображение.
Полей для референсных изображений у модели нет. Изображения объекта передаются в elements.

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

Больше двух ссылок: "images" accepts at most 2 items
Пустой массив: "images" requires at least 1 item
Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL
multi_shots: true без изображения или с двумя изображениями: Kling V3 multi-shot mode requires exactly one image

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

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

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

Если параметр не указан, используется и оплачивается 5.
При multi_shots: true сумма значений duration сцен в multi_prompt должна точно равняться этому числу. Если общая duration не задана, сумма должна быть равна 5.

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

Число вне диапазона, нецелое число либо строка вместо числа: "duration" is outside its supported range
Сумма длительностей сцен не равна duration: Kling V3 shot durations must sum to duration

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

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

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

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

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

Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [16:9 9:16 1:1]

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

Уровень качества: std генерирует в 720p, pro — в 1080p. Секунда в режиме pro стоит дороже. Используются имена std и pro, а не размеры в пикселях.

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

Если параметр не указан, используется и оплачивается pro.
4K, 720p и 1080p не принимаются: передайте std или pro.

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

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

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

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

Если параметр не указан, звук зависит от multi_shots: включён для многосценного запроса и выключен в остальных случаях. Передайте true или false, чтобы выбрать явно.

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

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

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

Включает режим раскадровки: видео состоит из сцен, перечисленных в multi_prompt. По умолчанию — false.

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

Требуется ровно одно изображение в images и multi_prompt с суммой длительностей сцен, равной duration. Без multi_shots: true поле multi_prompt отклоняется.
Проверки выполняются по порядку: одно изображение, наличие multi_prompt, затем длительности.

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

Значение не равно true или false: "multi_shots" must be a boolean
Нет изображения или передано больше одного: Kling V3 multi-shot mode requires exactly one image
Отсутствует multi_prompt: Kling V3 multi-shot mode requires multi_prompt
Сумма длительностей сцен не равна duration: Kling V3 shot durations must sum to duration

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

Сцены многосценного видео по порядку: от одного до пяти объектов с собственными промптами и длительностью.

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

Каждая сцена — объект с двумя обязательными полями. Другие поля не принимаются:
multi_prompt[].prompt (string, обязательно): что происходит в этой сцене, от 1 до 500 символов.
multi_prompt[].duration (integer, обязательно): длительность сцены в целых секундах, от 1 до 12.
Сумма длительностей сцен должна равняться duration запроса, либо 5, если duration не задана. Общая длительность — не более 15 секунд.
Допускается только при multi_shots: true.

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

Передано без multi_shots: true: "multi_prompt" requires multi_shots=true
Больше пяти сцен: "multi_prompt" accepts at most 5 items
Пустой массив: "multi_prompt" requires at least 1 item
У сцены нет prompt: "prompt" is required in "multi_prompt[0]"
У сцены нет duration: "duration" is required in "multi_prompt[0]"
Промпт сцены пустой или длиннее 500 символов: "multi_prompt[0].prompt" has an unsupported length
Длительность сцены вне диапазона 1–12 или не является целым числом: "multi_prompt[0].duration" is outside its supported range
Поле, отличное от prompt и duration: field "name" is not supported in "multi_prompt[0]"
Сумма длительностей сцен не равна duration: Kling V3 shot durations must sum to duration

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

До трёх именованных объектов — персонажей, товаров или предметов. Каждый один раз задаётся изображениями.

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

Массив из не более трёх объектов. Каждый объект принимает только следующие поля:
elements[].name (string, обязательно): имя элемента, не менее 1 символа.
elements[].description (string, необязательно): описание элемента. Если не задано, в качестве описания используется name.
elements[].element_input_urls (массив строк, обязательно): 1–4 общедоступные HTTPS-ссылки с изображениями элемента.
elements[].element_input_audio_urls (массив строк, необязательно): ровно одна общедоступная HTTPS-ссылка на аудио элемента.
elements[].start_time и elements[].end_time (целые числа, необязательно): время в миллисекундах, каждое значение от 0 до 30000. Передайте оба поля либо ни одного. end_time должно быть больше start_time, а разность end_time - start_time — от 3000 до 8000 (3–8 секунд).
Лимиты ссылок применяются отдельно к каждому элементу: у каждого может быть до четырёх изображений и одна аудиоссылка.

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

Больше трёх элементов: "elements" accepts at most 3 items
Элемент не является объектом: "elements[0]" must be an object
У элемента нет name: "name" is required in "elements[0]"
У элемента нет element_input_urls: "element_input_urls" is required in "elements[0]"
Пустое name: "elements[0].name" has an unsupported length
Больше четырёх ссылок: "elements[0].element_input_urls" accepts at most 4 items
Пустой массив element_input_urls: "elements[0].element_input_urls" requires at least 1 item
Ссылка не начинается с https://: "elements[0].element_input_urls[1]" must be a public HTTPS URL
Больше одной аудиоссылки: "elements[0].element_input_audio_urls" accepts at most 1 items
start_time или end_time вне диапазона 0–30000 либо не является целым числом: "elements[0].start_time" is outside its supported range
Поле, которое элемент не принимает: field "color" is not supported in "elements[0]"
Передано только одно из start_time и end_time, end_time не больше start_time либо фрагмент короче 3 с или длиннее 8 с: Kling V3 element segment must provide a 3-8 second start_time/end_time range

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

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

Шлюз проверяет только общедоступность HTTPS-ссылок на изображения, материалы элементов и аудио. До создания задачи не измеряются размер файла, формат или размеры изображения. Поэтому неподходящий для модели материал вызывает ошибку после отправки. Сообщение укажет, что изменить, а вся зарезервированная сумма вернётся.
Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

Правила многосценного режима

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

Правило	Сообщение
Передано `multi_prompt`, но `multi_shots` не равно `true`	`"multi_prompt" requires multi_shots=true`
При `multi_shots: true` в `images` не ровно одно изображение	`Kling V3 multi-shot mode requires exactly one image`
`multi_shots: true` без `multi_prompt`	`Kling V3 multi-shot mode requires multi_prompt`
Сумма длительностей сцен не равна `duration`, либо 5, если параметр не указан	`Kling V3 shot durations must sum to duration`

Многосценный режим только по тексту недоступен: такое видео всегда начинается с одного изображения.
Многосценный запрос оплачивается за duration секунд — сумму длительностей его сцен.

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

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

reference_images, reference_videos, reference_audios, generate_audio, seed, quality, watermark, task_type, output_format → field "reference_images" is not supported by model kling-v3 (с именем переданного поля).
Любое другое неизвестное поле → 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-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true
}'

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

Ролик со звуком длительностью 5 секунд на уровне pro (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-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true
}'

Первый кадр

Видео начинается с переданного изображения.

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-v3",
  "prompt": "The bottle slowly rotates on its pedestal while reflections move across the glass",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 5,
  "resolution": "pro",
  "sound": true
}'

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

Видео переходит от первого изображения ко второму на более дешёвом уровне std (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-v3",
  "prompt": "The camera moves from the bottle on the table to the singer on a neon stage in one continuous shot",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png",
    "https://cdn.beatapi.io/samples/neon-singer.png"
  ],
  "duration": 5,
  "resolution": "std"
}'

Многосценный режим

Две сцены по 3 секунды из одного первого кадра. Сумма длительностей (3 + 3) равна duration (6).

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-v3",
  "prompt": "A two-shot cinematic product reveal",
  "images": [
    "https://cdn.beatapi.io/samples/smart-bottle.png"
  ],
  "duration": 6,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": true,
  "multi_shots": true,
  "multi_prompt": [
    {
      "prompt": "Macro detail shot of the bottle with moving reflections",
      "duration": 3
    },
    {
      "prompt": "Wide hero reveal of the bottle on a dark pedestal",
      "duration": 3
    }
  ]
}'

Повторно используемый элемент

Один именованный элемент задаётся двумя изображениями. Его имя — product; описание необязательно.

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-v3",
  "prompt": "A slow cinematic camera orbit around the product",
  "duration": 5,
  "resolution": "pro",
  "elements": [
    {
      "name": "product",
      "description": "The featured water bottle",
      "element_input_urls": [
        "https://cdn.beatapi.io/samples/smart-bottle.png",
        "https://cdn.beatapi.io/samples/neon-singer.png"
      ]
    }
  ]
}'

Ответы

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

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

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 0.65,
      "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-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "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.65,
      "credits_settled": 0.65,
      "credits_refunded": 0,
      "credits_charged": 0.65,
      "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-v3",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-v3",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 0.65,
      "credits_settled": 0,
      "credits_refunded": 0.65,
      "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-v3",
  "prompt": "A dramatic product reveal of a glass water bottle, slow orbiting camera, soft studio reflections",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "pro",
  "sound": True
})
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"])

Оплата

sound не влияет на цену: она зависит только от duration и resolution. Тарифы одинаковы со звуком и без него.
Цена указана за секунду видео на выбранном уровне. В таблице ниже приведены 8-секундные ролики: разделите цену на 8, чтобы получить тариф — примерно $0.11 за секунду для `std` и$ 0.13 для pro.
Число секунд задаётся duration, либо равно 5, если параметр не указан. Для многосценного запроса это сумма длительностей сцен, равная duration. Значение указано в usage.billable_duration_seconds задачи.
Цена резервируется при создании задачи и окончательно списывается, когда видео готово. Если задача завершилась ошибкой, в том числе из-за модерации после отправки, средства возвращаются полностью.

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

Ошибка или признак проблемы	Причина	Что делать
400 `"resolution" must be one of: [std pro]`	Передано разрешение в пикселях, например `720p`, `1080p` или `4K`. Эта модель принимает названия уровней.	Передайте `std` (генерация в 720p) или `pro` (генерация в 1080p).
400 `Kling V3 multi-shot mode requires exactly one image`	`multi_shots: true` без изображения или с двумя изображениями.	Передайте одно изображение в `images`. Многосценного режима только по тексту нет.
400 `Kling V3 shot durations must sum to duration`	Сумма длительностей `multi_prompt` не равна `duration`, либо 5, если `duration` не задана.	Сумма длительностей сцен должна точно равняться `duration`, например 3 + 3 при `duration: 6`.
400 `"multi_prompt" requires multi_shots=true`	`multi_prompt` передан без `multi_shots: true`.	Добавьте `multi_shots: true` либо удалите `multi_prompt`.
400 `Kling V3 multi-shot mode requires multi_prompt`	`multi_shots: true` без `multi_prompt`.	Добавьте `multi_prompt` с одной-пятью сценами.
400 `Kling V3 element segment must provide a 3-8 second start_time/end_time range`	У элемента задано только одно из полей `start_time` и `end_time`, `end_time` не больше `start_time` либо фрагмент короче 3 или длиннее 8 секунд. Оба значения задаются в миллисекундах.	Передайте оба значения в миллисекундах, чтобы `end_time - start_time` было от 3000 до 8000.
400 `"elements[0].element_input_urls" accepts at most 4 items`	У одного элемента больше четырёх ссылок.	Оставьте до четырёх ссылок на элемент. Разные объекты разделите на отдельные элементы, всего не более трёх.
400 `field "reference_images" is not supported by model kling-v3`	У модели нет полей референсов, а также `generate_audio`, `seed` и `quality`.	Удалите поле. Изображения объекта передаются в `elements`.
400 `"duration" is outside its supported range`	Передано нецелое число, число вне диапазона 3–15 либо строка вместо числа.	Передайте целое число, например `5`.
Задача `failed` с `content_policy_violation`	Промпт, входное изображение или результат отклонены модерацией.	Измените промпт или изображения. Повтор без изменений снова завершится ошибкой; средства не списаны.
402 `insufficient_credits`	Баланс меньше резерва для выбранных длительности и уровня.	Пополните баланс, уменьшите `duration` либо используйте `std`.

Краткий справочник 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-v3

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

Поле отсутствует: "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 считается одним символом.
Обязателен во всех режимах, включая многосценный, где у каждой сцены также есть свой промпт в multi_prompt.

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

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

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

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

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

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

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

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

Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [16:9 9:16 1:1]

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

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

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

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

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

Если параметр не указан, используется и оплачивается 5.
При multi_shots: true сумма значений duration сцен в multi_prompt должна точно равняться этому числу. Если общая duration не задана, сумма должна быть равна 5.

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

Число вне диапазона, нецелое число либо строка вместо числа: "duration" is outside its supported range
Сумма длительностей сцен не равна duration: Kling V3 shot durations must sum to duration

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

До трёх именованных объектов — персонажей, товаров или предметов. Каждый один раз задаётся изображениями.

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

Массив из не более трёх объектов. Каждый объект принимает только следующие поля:
elements[].name (string, обязательно): имя элемента, не менее 1 символа.
elements[].description (string, необязательно): описание элемента. Если не задано, в качестве описания используется name.
elements[].element_input_urls (массив строк, обязательно): 1–4 общедоступные HTTPS-ссылки с изображениями элемента.
elements[].element_input_audio_urls (массив строк, необязательно): ровно одна общедоступная HTTPS-ссылка на аудио элемента.
elements[].start_time и elements[].end_time (целые числа, необязательно): время в миллисекундах, каждое значение от 0 до 30000. Передайте оба поля либо ни одного. end_time должно быть больше start_time, а разность end_time - start_time — от 3000 до 8000 (3–8 секунд).
Лимиты ссылок применяются отдельно к каждому элементу: у каждого может быть до четырёх изображений и одна аудиоссылка.

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

Больше трёх элементов: "elements" accepts at most 3 items
Элемент не является объектом: "elements[0]" must be an object
У элемента нет name: "name" is required in "elements[0]"
У элемента нет element_input_urls: "element_input_urls" is required in "elements[0]"
Пустое name: "elements[0].name" has an unsupported length
Больше четырёх ссылок: "elements[0].element_input_urls" accepts at most 4 items
Пустой массив element_input_urls: "elements[0].element_input_urls" requires at least 1 item
Ссылка не начинается с https://: "elements[0].element_input_urls[1]" must be a public HTTPS URL
Больше одной аудиоссылки: "elements[0].element_input_audio_urls" accepts at most 1 items
start_time или end_time вне диапазона 0–30000 либо не является целым числом: "elements[0].start_time" is outside its supported range
Поле, которое элемент не принимает: field "color" is not supported in "elements[0]"
Передано только одно из start_time и end_time, end_time не больше start_time либо фрагмент короче 3 с или длиннее 8 с: Kling V3 element segment must provide a 3-8 second start_time/end_time range

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

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

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

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

Одна ссылка: видео начинается с этого изображения. Две ссылки: images[0] задаёт первый кадр, images[1] — последний.
Многосценный режим (multi_shots: true) принимает ровно одно изображение.
Полей для референсных изображений у модели нет. Изображения объекта передаются в elements.

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

Больше двух ссылок: "images" accepts at most 2 items
Пустой массив: "images" requires at least 1 item
Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL
multi_shots: true без изображения или с двумя изображениями: Kling V3 multi-shot mode requires exactly one image

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

Сцены многосценного видео по порядку: от одного до пяти объектов с собственными промптами и длительностью.

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

Каждая сцена — объект с двумя обязательными полями. Другие поля не принимаются:
multi_prompt[].prompt (string, обязательно): что происходит в этой сцене, от 1 до 500 символов.
multi_prompt[].duration (integer, обязательно): длительность сцены в целых секундах, от 1 до 12.
Сумма длительностей сцен должна равняться duration запроса, либо 5, если duration не задана. Общая длительность — не более 15 секунд.
Допускается только при multi_shots: true.

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

Передано без multi_shots: true: "multi_prompt" requires multi_shots=true
Больше пяти сцен: "multi_prompt" accepts at most 5 items
Пустой массив: "multi_prompt" requires at least 1 item
У сцены нет prompt: "prompt" is required in "multi_prompt[0]"
У сцены нет duration: "duration" is required in "multi_prompt[0]"
Промпт сцены пустой или длиннее 500 символов: "multi_prompt[0].prompt" has an unsupported length
Длительность сцены вне диапазона 1–12 или не является целым числом: "multi_prompt[0].duration" is outside its supported range
Поле, отличное от prompt и duration: field "name" is not supported in "multi_prompt[0]"
Сумма длительностей сцен не равна duration: Kling V3 shot durations must sum to duration

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

Включает режим раскадровки: видео состоит из сцен, перечисленных в multi_prompt. По умолчанию — false.

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

Требуется ровно одно изображение в images и multi_prompt с суммой длительностей сцен, равной duration. Без multi_shots: true поле multi_prompt отклоняется.
Проверки выполняются по порядку: одно изображение, наличие multi_prompt, затем длительности.

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

Значение не равно true или false: "multi_shots" must be a boolean
Нет изображения или передано больше одного: Kling V3 multi-shot mode requires exactly one image
Отсутствует multi_prompt: Kling V3 multi-shot mode requires multi_prompt
Сумма длительностей сцен не равна duration: Kling V3 shot durations must sum to duration

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

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

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

Если параметр не указан, используется и оплачивается pro.
4K, 720p и 1080p не принимаются: передайте std или pro.

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

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

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

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

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

Если параметр не указан, звук зависит от multi_shots: включён для многосценного запроса и выключен в остальных случаях. Передайте true или false, чтобы выбрать явно.

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

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

Ответ

Ошибки

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

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

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

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

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

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

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

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

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

Правила многосценного режима

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

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

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

Первый кадр

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

Многосценный режим

Повторно используемый элемент

Ответы

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

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

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

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

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

Оплата

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

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

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

Заголовки

Запрос

Ответ

Ошибки

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

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

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

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

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

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

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

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

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

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

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