Перейти к содержанию

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"
}

Типовой сценарий

  1. Создайте задачу через POST /kling/images/generations.
  2. Сохраните data.task_id из ответа.
  3. Опрашивайте GET /kling/images/generations/{taskId} до финального статуса.
  4. Заберите изображения из 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,.