Kling
Kling — семейство моделей для генерации изображений через CDNvideo AI Hub media API.
Base URL
https://api.cdnvideo.ru/app/aihub-router/v1/media
Для работы используется обычный ключ AI Hub в заголовке Authorization. Модель для маршрутизации передаётся в X-Model:
Authorization: Bearer ${AIHUB_API_KEY}
X-Model: kling-3.0-image
Сейчас для этой вкладки используется модель kling-3.0-image.
Асинхронная обработка
Kling возвращает task_id, а не готовое изображение. После создания задачи опрашивайте GET /kling/images/generations/{taskId} до финального статуса.
Создание задачи
POST /kling/images/generations
Метод создаёт задачу генерации изображения. Поддерживаются text-to-image и image-to-image сценарии. Для image-to-image передайте поле image.
Параметры запроса
| Поле | Тип | Обязательное | По умолчанию | Описание |
|---|---|---|---|---|
model_name |
string |
Нет | kling-v1 |
Имя модели на стороне Kling. Для kling-3.0-image используйте kling-v3. Возможные значения: kling-v1, kling-v1-5, kling-v2, kling-v2-new, kling-v2-1, kling-v3. |
prompt |
string |
Да | — | Текстовый промпт. Может включать положительные и отрицательные описания. Максимальная длина: 2500 символов. |
negative_prompt |
string |
Нет | Пусто | Негативный промпт до 2500 символов. В image-to-image сценарии, когда image не пустой, не поддерживается. Рекомендуется включать негативные описания в основной prompt. |
image |
string |
Нет | Пусто | Референс-изображение для image-to-image: публичный URL или Base64-строка без префикса data:image/...;base64,. Если используется image_reference, поле обязательно. |
element_list |
array<object> |
Нет | Пусто | Список subject reference из entity library. Суммарное количество subject reference и reference images не должно превышать 10. |
element_list[].element_id |
string или integer |
Да, если передан element_list |
— | ID сущности из entity library. |
resolution |
string |
Нет | 1k |
Чёткость результата. Возможные значения: 1k, 2k. Поддержка зависит от версии модели. |
n |
integer |
Нет | 1 |
Количество генерируемых изображений. Диапазон: 1–9. |
aspect_ratio |
string |
Нет | 16:9 |
Соотношение сторон. Возможные значения: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9. Поддержка зависит от версии модели. |
watermark_info |
object |
Нет | Пусто | Настройка одновременной генерации результата с водяным знаком. Кастомные водяные знаки сейчас не поддерживаются. |
watermark_info.enabled |
boolean |
Нет | — | true — сгенерировать результат с водяным знаком, false — без водяного знака. |
callback_url |
string |
Нет | — | URL для callback-уведомления при изменении статуса задачи. |
external_task_id |
string |
Нет | — | Пользовательский ID задачи. Не заменяет системный task_id, но позволяет искать задачу по внешнему ID. Должен быть уникальным в рамках пользователя. |
Требования к image
| Требование | Описание |
|---|---|
| Форматы | .jpg, .jpeg, .png. |
| Размер файла | До 10MB. |
| Размер изображения | Ширина и высота не меньше 300px. |
| Соотношение сторон | От 1:2.5 до 2.5:1. |
| Base64 | Передавайте только Base64-строку без префикса data:image/png;base64,. |
Пример text-to-image
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/kling/images/generations \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: kling-3.0-image" \
-d '{
"model_name": "kling-v3",
"prompt": "Generate images of the numbers 1 through 9",
"resolution": "2k",
"n": 9,
"aspect_ratio": "3:2"
}'
Пример image-to-image
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/kling/images/generations \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: kling-3.0-image" \
-d '{
"model_name": "kling-v3",
"prompt": "Turn this reference into a cinematic product render with soft studio lighting",
"image": "https://example.com/reference.png",
"resolution": "1k",
"n": 1,
"aspect_ratio": "1:1"
}'
Пример с subject reference
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/kling/images/generations \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: kling-3.0-image" \
-d '{
"model_name": "kling-v3",
"prompt": "Create a stylish editorial poster using the referenced subjects",
"element_list": [
{"element_id": "160"},
{"element_id": "161"},
{"element_id": "159"}
],
"resolution": "2k",
"n": 3,
"aspect_ratio": "3:2"
}'
Ответ
{
"code": 0,
"message": "SUCCEED",
"data": {
"task_id": "868892585292099640",
"task_status": "submitted",
"created_at": 1775188654357,
"updated_at": 1775188654357,
"task_info": {
"parent_video": null
}
},
"request_id": "68329d65-ee21-4013-9aa6-f0bc2cc07744"
}
Получение статуса задачи
GET /kling/images/generations/{taskId}
Метод возвращает статус задачи и результат генерации, когда задача завершена.
Path-параметры
| Параметр | Тип | Обязательное | Описание |
|---|---|---|---|
taskId |
string |
Да | ID задачи из поля data.task_id. |
Пример curl
curl https://api.cdnvideo.ru/app/aihub-router/v1/media/kling/images/generations/868892585292099640 \
-H "Authorization: Bearer ${AIHUB_API_KEY}" \
-H "Content-Type: application/json" \
-H "X-Model: kling-3.0-image"
Ответ
{
"code": 0,
"message": "SUCCEED",
"data": {
"task_id": "868892585292099640",
"task_status": "succeed",
"created_at": 1775188654357,
"updated_at": 1775188656386,
"task_status_msg": "",
"task_info": {
"parent_video": null
},
"task_result": {
"images": [
{
"url": "https://example.com/image-1.png",
"index": 0
}
],
"result_type": "images",
"series_images": null
},
"final_unit_deduction": "0"
},
"request_id": "a699ea31-8369-4b80-a796-7ca574d5ddf8"
}
Пример ошибки обработки
{
"code": 0,
"message": "SUCCEED",
"data": {
"task_id": "868892585292099640",
"task_status": "failed",
"task_status_msg": "Image format is invalid",
"task_result": {
"images": null,
"result_type": null,
"series_images": null
}
},
"request_id": "a699ea31-8369-4b80-a796-7ca574d5ddf8"
}
Типовой сценарий
- Создайте задачу через
POST /kling/images/generations. - Сохраните
data.task_idиз ответа. - Опрашивайте
GET /kling/images/generations/{taskId}до финального статуса. - Заберите изображения из
data.task_result.images.
Ограничения
- Для
kling-3.0-imageуказывайтеX-Model: kling-3.0-imageиmodel_name: kling-v3. promptиnegative_promptподдерживают до2500символов.negative_promptне поддерживается в image-to-image сценарии, когда переданimage.nпринимает значения от1до9.- Суммарное количество subject reference и reference images не должно превышать
10. - Base64-изображения передаются без префикса
data:image/...;base64,.