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), плюс фиксированная плата за каждое референсное изображение и каждый элемент. Неудачная задача ничего не стоит.
Открывает модель в 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 выполняется заново.
Как выполняется запрос
Создайте задачу
Отправьте перечисленные ниже параметры методом 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
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
Пример
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 lengthnameсодержит недопустимые символы или является зарезервированным именем: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]"
Пример
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 с указанием материала. Средства не списываются.
- Шлюз читает каждую ссылку в
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_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>.
Если в запросе несколько неверных полей, сообщение называет только одно из них; исправьте его и отправьте запрос снова.
Примеры запросов
Изображение по тексту
Одно изображение 2K по промпту.
Четыре варианта в одной задаче
Четыре изображения 4K по одному промпту; каждое оплачивается по цене 4K.
Редактирование одного изображения
Превращение фотографии товара в рекламное изображение с новой композицией.
Объединение нескольких изображений
Называйте каждый референс в промпте его упоминанием.
Именованный элемент
Покажите один объект с нескольких ракурсов как элемент и разместите его по имени.
Ответы
Создание задачи (201)
Объект задачи. Поле output равно null, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.
Успешно завершённая задача
GET /v1/tasks/{task_id} возвращает HTTP 200 со status: "succeeded" и результатом в data.output.
Поля результата
Задача, завершившаяся ошибкой
Если задача завершилась ошибкой, GET /v1/tasks/{task_id} всё равно возвращает HTTP 200: сведения об ошибке находятся в теле ответа. Зарезервированная сумма возвращается полностью, поэтому списания нет.
Полный пример
Создайте задачу, дождитесь её завершения с интервалом опроса, указанным сервером, и выведите ссылки на результаты. Задайте BEATAPI_API_KEY в переменной окружения и установите requests.
Оплата
- Каждое изображение оценивается по
resolution(таблица ниже) и умножается наn. Каждая ссылка вimagesи каждый элемент вelementsдобавляют фиксированную плату один раз за задачу. - Стоимость резервируется при создании задачи на балансе и в лимите ключа, если он установлен. Запрос, отклонённый до создания задачи, не оплачивается.
- Успешная задача оплачивается по числу доставленных изображений. Неудачная задача возвращает резерв полностью: тогда
credits_refundedравноcredits_reserved, аcredits_chargedиcredits_settledравны 0.
Текущие базовые цены совпадают с указанными на странице цен. Если для аккаунта согласована скидка, стоимость будет ниже. Фактически списанная сумма всегда указана в data.usage задачи.
Частые ошибки
Краткий справочник HTTP-ошибок
Ошибки до создания задачи возвращаются с HTTP-статусом, отличным от 2xx, без списания средств. Обрабатывайте error.code или error.retryable; причина указана в message. Полный список и правила повторов приведены в разделе ошибок.
Аутентификация
Передавайте API-ключ в виде Authorization: Bearer <BEATAPI_API_KEY>.
Заголовки
Передавайте тело запроса в JSON с заголовком Content-Type: application/json. Idempotency-Key необязателен. Для каждого логического запроса используйте уникальное значение длиной не более 255 символов и повторно используйте его только для отправки точно такого же тела. В течение 24 часов повтор с тем же ключом и телом возвращает первый ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом возвращает 409 idempotency_conflict. Ответы, отличные от 2xx, не сохраняются, поэтому повтор после 400 или 402 выполняется заново.
Запрос
Модель, которую нужно вызвать.
Значение: 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
Что нарисовать или что изменить в референсных изображениях: объект, стиль, освещение, композиция и текст, который должен появиться, с упоминанием каждого входа через @.
Длина: 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
Форма изображений в виде ширина:высота.
Допустимые значения: 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]
Именованные объекты, например персонаж, животное, реквизит, костюм или сцена: каждый показан на 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 lengthnameсодержит недопустимые символы или является зарезервированным именем: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"
]
}
]
Референсные изображения для редактирования или объединения. В промпте называйте их @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"
]
Сколько изображений создать в этой задаче. Для всех изображений используются одни и те же промпт, входные данные, соотношение сторон и уровень.
По умолчанию: 1
Диапазон: 1–9
- Если поле не передано, используется
1. - Каждое изображение оплачивается по цене
resolution, поэтомуnумножает часть цены за изображения. Плата за референсные изображения и элементы начисляется один раз за задачу, а не за каждое изображение. - Изображения оплачиваются по числу доставленных.
Если значение неверно
- Число вне диапазона, нецелое число либо строка вместо числа:
"n" is outside its supported range
Класс размера изображений: 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, пока задача не завершится успешно. Поля с пометкой «во время выполнения» исчезают после завершения задачи.

