Перейти к навигации

Kling Image 4.0

Модель изображений Kling. Генерирует или редактирует от 1 до 9 изображений за задачу по тексту, до 10 референсным изображениям и именованным элементам в 2K, 4K или 8K.

  • Асинхронно: запрос на создание сразу возвращает ID задачи; изображения появляются, когда задача завершается успешно.
  • Одна задача создаёт от 1 до 9 изображений через n; каждое изображение оплачивается по тарифу своего resolution.
  • Текст в изображение или редактирование и объединение до 10 референсных изображений и именованных elements вместе, переданных публичными HTTPS-ссылками.
  • Называйте входные данные в промпте: @image_1, @image_2 … для images по порядку и @ с именем для элемента.
  • Цена за изображение зависит от resolution (2K, 4K или 8K), плюс фиксированная плата за каждое референсное изображение и каждый элемент. Неудачная задача ничего не стоит.
POST/v1/images/tasksПопробовать

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

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

POST https://api.beatapi.io/v1/images/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 выполняется заново.

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

1

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

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

2

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

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

3

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

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

Режимы ввода

РежимОбязательные данныеПримечания
Изображение по текстуmodel, promptНе передавайте images и elements.
Редактирование или объединение изображенийmodel, prompt, а также images, elements или оба поляВместе не больше 10 референсных изображений и элементов. Назовите каждый вход в prompt: @image_1 для первого изображения, @ с именем для элемента.

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

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

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

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

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

  • Поле отсутствует: "model" is required
  • Неизвестный ID модели: "model" kling-image-v9 is not catalogued
  • На этот адрес API отправлена видеомодель: "model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint

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

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

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

  • Длина измеряется в символах. Иероглиф CJK считается одним символом.
  • Упоминания: images — это @image_1, @image_2 … в порядке списка, а элемент — @ и его name.
  • Каждый @image_N должен указывать на изображение из того же запроса. @image_3 при двух изображениях отклоняется при создании задачи.

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

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

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

Референсные изображения для редактирования или объединения. В промпте называйте их @image_1, @image_2 … в порядке списка.

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

  • Каждый элемент должен быть публичной ссылкой https:// на файл JPEG или PNG. При создании задачи BeatAPI читает каждую ссылку и отклоняет ту, что не является таким изображением или нарушает ограничения ниже, указывая её позицию (images[0] — первая ссылка).
  • images и elements вместе — не больше 10.
  • Каждая ссылка добавляет к задаче фиксированную плату (см. раздел цен).

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

  • Превышено максимальное число элементов: "images" accepts at most 10 items
  • Пустой массив: "images" requires at least 1 item
  • Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL
  • Ссылка не на файл JPEG или PNG (здесь WebP): "images[0]" is not a PNG or JPEG image: the URL returned image/webp
  • Ссылка отвечает ошибкой: "images[0]" could not be downloaded: the URL returned HTTP 404
  • Больше 10 изображений и элементов вместе: Kling Image 4.0 takes at most 10 images and elements together

Пример

"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
]

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

Именованные объекты, например персонаж, животное, реквизит, костюм или сцена: каждый показан на 2–4 изображениях и упоминается в промпте как @ и его name.

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

  • Массив объектов. Каждый объект принимает только эти ключи:
  • 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[].tag (строка, необязательно): что представляет собой элемент.
  • elements[].description (string, необязательно): описание элемента, не более 100 символов.
  • Элементы состоят только из изображений: видео- и голосовые элементы эта модель не принимает.
  • images и elements вместе — не больше 10. Каждый элемент добавляет к задаче фиксированную плату независимо от числа изображений в нём.

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

  • Больше десяти элементов: "elements" accepts at most 10 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 пустое или длиннее 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].element_input_urls" requires at least 2 item
  • Больше четырёх изображений: "elements[0].element_input_urls" accepts at most 4 items
  • 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 "element_input_video_urls" is not supported in "elements[0]"

Пример

"elements": [
{
"name": "Bottle",
"tag": "prop",
"description": "A matte smart water bottle",
"element_input_urls": [
"https://your-cdn.example.com/bottle-front.png",
"https://your-cdn.example.com/bottle-side.png"
]
}
]

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

Форма изображений в виде ширина:высота.

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

  • Если поле не передано, используется auto: модель выбирает кадр по промпту и изображениям, если они есть. Передайте соотношение, если форма важна.

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

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

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

Класс размера изображений: 2K, 4K или 8K. У каждого уровня своя цена за изображение.

Допустимые значения: 2K, 4K, 8K
По умолчанию: 2K

  • Если поле не передано, используется и оплачивается 2K.
  • Изображения 2K и 4K возвращаются в PNG, 8K — в JPEG.
  • Пишите K заглавной: 2k отклоняется. Уровня 1K нет, а размеры в пикселях, например 2048x2048, не принимаются.

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

  • Значение не из списка (например, 1K или 2k): "resolution" must be one of: [2K 4K 8K]

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

Сколько изображений создать в этой задаче. Для всех изображений используются одни и те же промпт, входные данные, соотношение сторон и уровень.

По умолчанию: 1
Диапазон: 1–9

  • Если поле не передано, используется 1.
  • Каждое изображение оплачивается по цене resolution, поэтому n умножает часть цены за изображения. Плата за референсные изображения и элементы начисляется один раз за задачу, а не за каждое изображение.
  • Изображения оплачиваются по числу доставленных.

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

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

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

  • n задаёт от 1 до 9 изображений за один запрос; каждое изображение оплачивается по тарифу своего разрешения, а каждое изображение в images и каждый элемент оплачиваются ещё один раз за запрос.
  • В промпте изображения по порядку называются @image_1, @image_2 …, а элементы — @ и их имя; каждый @image_N должен указывать на изображение из того же запроса.
  • Элемент — это 2–4 изображения одного объекта в element_input_urls, первое — основной вид; images и elements вместе — не больше 10.
  • Имена элементов содержат 1–20 букв, цифр, подчёркиваний или китайских иероглифов и уникальны без учёта регистра. Запрещены image_N, video_N, voice_N, keyframe_N, object_N, audio_N, first_frame, last_frame.
  • Изображения в images — JPEG или PNG, до 20 МБ, с соотношением сторон от 2:5 до 5:2 и не больше 8192 px по каждой стороне.
  • 2K и 4K возвращаются в PNG, 8K — в JPEG; aspect_ratio: auto — кадр выбирает модель по промпту и изображениям, если они есть.

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

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

МатериалОграничения, проверяемые до создания задачи
Изображенияширина и высота: не более 8192 пикс.; соотношение сторон (ширина ÷ высота): 0.4–2.5; каждый файл не более 20 MB
  • Шлюз читает каждую ссылку в images до создания задачи и отклоняет выходящую за эти ограничения с сообщением, где она названа, например images[0] has an aspect ratio of 3.10 (width/height); this model takes 0.4 to 2.5. Плата не взимается.
  • Изображения элементов (element_input_urls) до создания задачи проверяются только на то, что это публичные HTTPS-ссылки. Используйте файлы JPEG или PNG в тех же пределах.
  • Файл находится на вашем устройстве? Загрузите его через POST /v1/files и передайте полученный data.url.

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

У каждого входа своё упоминание:

УпоминаниеЧто обозначаетКогда доступно
@image_1, @image_2 …images в порядке спискаПередано не меньше стольких изображений
@ + имя элементаЭлемент с этим nameЭлемент присутствует в elements
  • @image_N без соответствующего изображения отклоняется при создании задачи, например the prompt names @image_2, which this request does not send.

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

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

  • output_format, quality, seed, background, size, enhance_prompt → field "output_format" is not supported by model kling-image-v4 (с тем полем, которое вы передали).
  • Любое другое неизвестное поле → unknown field: <name>.

Если в запросе несколько неверных полей, сообщение называет только одно из них; исправьте его и отправьте запрос снова.

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

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
"aspect_ratio": "16:9",
"resolution": "2K"
}'

Изображение по тексту

Одно изображение 2K по промпту.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
"aspect_ratio": "16:9",
"resolution": "2K"
}'

Четыре варианта в одной задаче

Четыре изображения 4K по одному промпту; каждое оплачивается по цене 4K.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A minimalist poster of a lighthouse on a cliff at dawn, soft pastel colours, generous empty sky",
"aspect_ratio": "3:4",
"resolution": "4K",
"n": 4
}'

Редактирование одного изображения

Превращение фотографии товара в рекламное изображение с новой композицией.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "Keep the bottle in @image_1 exactly as it is. Place it on a sunlit kitchen counter with a soft reflection under it.",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png"
],
"resolution": "2K"
}'

Объединение нескольких изображений

Называйте каждый референс в промпте его упоминанием.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "Place the bottle from @image_1 on a neon-lit stage like the one in @image_2. Keep the bottle label readable.",
"images": [
"https://cdn.beatapi.io/samples/smart-bottle.png",
"https://cdn.beatapi.io/samples/neon-singer.png"
],
"aspect_ratio": "16:9",
"resolution": "2K"
}'

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

Покажите один объект с нескольких ракурсов как элемент и разместите его по имени.

curl --request POST \
--url https://api.beatapi.io/v1/images/tasks \
--header "Authorization: Bearer $BEATAPI_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
"model": "kling-image-v4",
"prompt": "A product shot of @Bottle on a marble bathroom shelf beside folded towels, morning light",
"elements": [
{
"name": "Bottle",
"tag": "prop",
"element_input_urls": [
"https://your-cdn.example.com/bottle-front.png",
"https://your-cdn.example.com/bottle-side.png"
]
}
],
"aspect_ratio": "1:1",
"resolution": "2K"
}'

Ответы

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

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

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "image",
"capability_id": "kling-image-v4",
"capability_version": 1,
"media_type": "image",
"model": "kling-image-v4",
"status": "queued",
"stage": "queued",
"created_at": 1791993600,
"updated_at": 1791993600,
"completed_at": null,
"poll_after_seconds": 5,
"output": null,
"usage": {
"credits_reserved": 0.0593,
"credits_settled": 0,
"credits_refunded": 0,
"credits_charged": 0.0593
},
"request_id": "req_5f0c2a9e4b7d4e31",
"error_code": null,
"error_message": null
}
}
ПолеТипОписание
data.idstringID задачи: префикс task_ и 32 буквы или цифры. Используется для опроса и сопоставления событий вебхука.
data.objectstringВсегда task.
data.task_kindstringimage или video.
data.capability_idstringID модели из вашего запроса.
data.capability_versionintegerВерсия контракта модели, сейчас 1.
data.media_typestringimage или video.
data.modelstringID модели из запроса, совпадает с capability_id.
data.statusstringqueued, processing, succeeded или failed. Только последние два состояния являются конечными.
data.stagestringПовторяет status; сохранено для совместимости со старыми клиентами.
data.created_atintegerВремя создания задачи, в секундах Unix.
data.updated_atintegerВремя последнего изменения, в секундах Unix.
data.completed_atinteger | nullВремя завершения, в секундах Unix. Во время выполнения равно null.
data.poll_after_secondsintegerВо время выполнения: сколько секунд ждать перед следующей проверкой (5 для изображений, 8 для видео).
data.typical_secondsobjectВо время выполнения, при достаточном числе недавних задач: время завершения p50 и p90 в секундах за последний период window, рассчитанное по samples задачам.
data.outputobject | nullРезультат. Равно null, пока status не станет succeeded. Поля результата описаны ниже.
data.usage.credits_reservednumberСумма USD, зарезервированная на балансе при создании задачи.
data.usage.credits_chargednumberСтоимость задачи в USD; 0, если задача завершилась ошибкой.
data.usage.credits_settlednumberОкончательно списанная сумма USD. Устанавливается после успешного завершения, иначе 0.
data.usage.credits_refundednumberСумма USD, возвращённая на баланс. После регистрации возврата по неудачной задаче равна зарезервированной сумме.
data.usage.billable_duration_secondsintegerТолько для видео: длительность в секундах, по которой рассчитана цена. Отсутствует, если модель не сообщает длительность.
data.request_idstringID запроса. Укажите его при обращении в поддержку.
data.error_codestring | nullКод ошибки; null, если задача не завершилась ошибкой.
data.error_messagestring | nullОписание проблемы и способа её исправить; null, если задача не завершилась ошибкой.

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

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

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

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

ПолеТипОписание
output.mediaobject[]Созданные файлы: по одному элементу на каждое доставленное изображение, не больше n.
output.media[].typestringВсегда image.
output.media[].urlstringHTTPS-ссылка на сохранённое изображение. Скачайте его и храните у себя: срок доступности ссылки не гарантируется.
output.media[].mime_typestringТип сохранённого файла: image/png для 2K и 4K, image/jpeg для 8K.
output.r2_urlstringПовтор первой ссылки на материал для старых клиентов. Вместо этого используйте media.

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

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

{
"data": {
"id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
"object": "task",
"task_kind": "image",
"capability_id": "kling-image-v4",
"capability_version": 1,
"media_type": "image",
"model": "kling-image-v4",
"status": "failed",
"stage": "failed",
"created_at": 1791993600,
"updated_at": 1791993690,
"completed_at": 1791993690,
"output": null,
"usage": {
"credits_reserved": 0.0593,
"credits_settled": 0,
"credits_refunded": 0.0593,
"credits_charged": 0
},
"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_codestringbad_request или content_policy_violation означают, что запрос нужно изменить. При processing_unavailable, processing_timeout, processing_failed или result_transfer_failed можно повторить позже. См. ошибки.
data.error_messagestringСообщение с причиной ошибки и рекомендацией по исправлению.
data.retryablebooleanПрисутствует только у неудачной задачи. Значение true означает, что повтор того же запроса может завершиться успешно.
data.usageobjectПосле регистрации возврата (обычно сразу при ошибке): 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/images/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-image-v4",
"prompt": "A cinematic storefront campaign image at blue hour, warm light spilling from the windows onto wet pavement",
"aspect_ratio": "16:9",
"resolution": "2K"
})
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"])

Оплата

  • Каждое изображение оценивается по resolution (таблица ниже) и умножается на n. Каждая ссылка в images и каждый элемент в elements добавляют фиксированную плату один раз за задачу.
  • Стоимость резервируется при создании задачи на балансе и в лимите ключа, если он установлен. Запрос, отклонённый до создания задачи, не оплачивается.
  • Успешная задача оплачивается по числу доставленных изображений. Неудачная задача возвращает резерв полностью: тогда credits_refunded равно credits_reserved, а credits_charged и credits_settled равны 0.

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

ВариантБазовая цена (USD)
1 изображение · 2K$0.0593
1 изображение · 4K$0.0893
1 изображение · 8K$0.1486
Каждое референсное изображение в images и каждый элемент в elements, один раз за задачу$0.0026

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

Ошибка или признак проблемыПричинаЧто делать
400 "resolution" must be one of: [2K 4K 8K]Передано 1K, строчное 2k или размер в пикселях вроде 2048x2048.Передайте 2K, 4K или 8K либо не передавайте поле.
400 "n" is outside its supported rangen больше 9, меньше 1, дробное число или строка.Передайте целое число от 1 до 9; для большего числа изображений создайте ещё одну задачу.
400 Kling Image 4.0 takes at most 10 images and elements togetherБольше 10 записей в images и elements вместе.Передавайте не больше 10 в сумме; несколько изображений одного объекта объедините в один элемент.
400 the prompt names @image_3, which this request does not sendУпоминание с номером больше последней ссылки в images.Нумеруйте упоминания с @image_1 в порядке списка или добавьте недостающее изображение.
400 elements[0].name "image_1" is not a name Kling V4 acceptsЗарезервированное имя или имя с пробелами, дефисами или другими символами.Используйте 1–20 букв, цифр, подчёркиваний или китайских иероглифов, например Bottle.
400 "images[0]" is not a PNG or JPEG image: the URL returned image/webpФайл WebP, GIF или HEIC либо ссылка, которая возвращает веб-страницу.Преобразуйте файл в JPEG или PNG либо загрузите его через POST /v1/files и используйте data.url.
400 field "output_format" is not supported by model kling-image-v4Передан параметр другой модели изображений: output_format, seed, quality, size, background, enhance_prompt.Удалите этот параметр.
Задача failed с content_policy_violationПромпт, референсное или созданное изображение отклонены модерацией.Измените промпт или изображение. Повтор без изменений снова завершится ошибкой; средства не списаны.
Задача failed с processing_timeoutИзображения не были готовы в пределах окна обработки.Повторите запрос: за неудачную задачу средства возвращены.
403 forbidden на аккаунте без пополненийБонус можно использовать только с некоторыми моделями.Пополните баланс один раз либо выберите модель, доступную за счёт бонуса.

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

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

AuthorizationBearer

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

Заголовки

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

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

Запрос

This endpoint expects an object.
modelenumОбязательный

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

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

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

  • Поле отсутствует: "model" is required
  • Неизвестный ID модели: "model" kling-image-v9 is not catalogued
  • На этот адрес API отправлена видеомодель: "model" kling-v4 is served by POST /v1/videos/tasks, not this endpoint
Допустимые значения:
promptstringОбязательный1-20000 characters

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

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

  • Длина измеряется в символах. Иероглиф CJK считается одним символом.
  • Упоминания: images — это @image_1, @image_2 … в порядке списка, а элемент — @ и его name.
  • Каждый @image_N должен указывать на изображение из того же запроса. @image_3 при двух изображениях отклоняется при создании задачи.

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

  • Поле отсутствует: "prompt" is required
  • Пустое значение или превышена допустимая длина: "prompt" has an unsupported length
  • Упоминание изображения, которого нет в запросе: the prompt names @image_3, which this request does not send
aspect_ratioenumОпциональныйПо умолчанию auto

Форма изображений в виде ширина:высота.

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

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

  • Если поле не передано, используется auto: модель выбирает кадр по промпту и изображениям, если они есть. Передайте соотношение, если форма важна.

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

  • Значение отсутствует в списке допустимых: "aspect_ratio" must be one of: [auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 21:9]
elementslist of objectsОпциональный

Именованные объекты, например персонаж, животное, реквизит, костюм или сцена: каждый показан на 2–4 изображениях и упоминается в промпте как @ и его name.

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

  • Массив объектов. Каждый объект принимает только эти ключи:
  • 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[].tag (строка, необязательно): что представляет собой элемент.
  • elements[].description (string, необязательно): описание элемента, не более 100 символов.
  • Элементы состоят только из изображений: видео- и голосовые элементы эта модель не принимает.
  • images и elements вместе — не больше 10. Каждый элемент добавляет к задаче фиксированную плату независимо от числа изображений в нём.

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

  • Больше десяти элементов: "elements" accepts at most 10 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 пустое или длиннее 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].element_input_urls" requires at least 2 item
  • Больше четырёх изображений: "elements[0].element_input_urls" accepts at most 4 items
  • 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 "element_input_video_urls" is not supported in "elements[0]"

Пример

"elements": [
  {
    "name": "Bottle",
    "tag": "prop",
    "description": "A matte smart water bottle",
    "element_input_urls": [
      "https://your-cdn.example.com/bottle-front.png",
      "https://your-cdn.example.com/bottle-side.png"
    ]
  }
]
imageslist of stringsОпциональный

Референсные изображения для редактирования или объединения. В промпте называйте их @image_1, @image_2 … в порядке списка.

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

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

  • Каждый элемент должен быть публичной ссылкой https:// на файл JPEG или PNG. При создании задачи BeatAPI читает каждую ссылку и отклоняет ту, что не является таким изображением или нарушает ограничения ниже, указывая её позицию (images[0] — первая ссылка).
  • images и elements вместе — не больше 10.
  • Каждая ссылка добавляет к задаче фиксированную плату (см. раздел цен).

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

  • Превышено максимальное число элементов: "images" accepts at most 10 items
  • Пустой массив: "images" requires at least 1 item
  • Ссылка не начинается с https://: "images[0]" must be a public HTTPS URL
  • Ссылка не на файл JPEG или PNG (здесь WebP): "images[0]" is not a PNG or JPEG image: the URL returned image/webp
  • Ссылка отвечает ошибкой: "images[0]" could not be downloaded: the URL returned HTTP 404
  • Больше 10 изображений и элементов вместе: Kling Image 4.0 takes at most 10 images and elements together

Пример

"images": [
  "https://cdn.beatapi.io/samples/smart-bottle.png",
  "https://cdn.beatapi.io/samples/neon-singer.png"
]
nintegerОпциональный1-9По умолчанию 1

Сколько изображений создать в этой задаче. Для всех изображений используются одни и те же промпт, входные данные, соотношение сторон и уровень.

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

Диапазон: 1–9

  • Если поле не передано, используется 1.
  • Каждое изображение оплачивается по цене resolution, поэтому n умножает часть цены за изображения. Плата за референсные изображения и элементы начисляется один раз за задачу, а не за каждое изображение.
  • Изображения оплачиваются по числу доставленных.

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

  • Число вне диапазона, нецелое число либо строка вместо числа: "n" is outside its supported range
resolutionenumОпциональныйПо умолчанию 2K

Класс размера изображений: 2K, 4K или 8K. У каждого уровня своя цена за изображение.

Допустимые значения: 2K, 4K, 8K

По умолчанию: 2K

  • Если поле не передано, используется и оплачивается 2K.
  • Изображения 2K и 4K возвращаются в PNG, 8K — в JPEG.
  • Пишите K заглавной: 2k отклоняется. Уровня 1K нет, а размеры в пикселях, например 2048x2048, не принимаются.

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

  • Значение не из списка (например, 1K или 2k): "resolution" must be one of: [2K 4K 8K]
Допустимые значения:

Ответ

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

Ошибки

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