Инструкция по интеграции Kling Videos Generation API

В этой статье представлена инструкция по интеграции Kling Videos Generation API, который позволяет создавать официальные видео Kling с помощью пользовательских параметров.

Процесс подачи заявки

Для использования API необходимо сначала подать заявку на соответствующую услугу на странице Kling Videos Generation API. После перехода на страницу нажмите кнопку «Acquire», как показано на рисунке:

Если вы не вошли в систему или не зарегистрированы, вас автоматически перенаправят на страницу входа, где можно зарегистрироваться и войти. После входа вы автоматически вернетесь на текущую страницу. При первом запросе предоставляется бесплатный лимит, позволяющий использовать API бесплатно.

Основное использование

Сначала рассмотрим базовый способ использования: вводим подсказку prompt, действие action, ссылку на начальное изображение start_image_url и модель model, чтобы получить обработанный результат. Для начала нужно передать поле action со значением text2video. Оно включает три типа действий: генерация видео из текста (text2video), генерация видео из изображения (image2video) и расширение видео (extend). Далее необходимо указать модель model. В настоящее время доступны модели: kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1. Подробности приведены ниже:

Здесь мы видим настройки заголовков запроса (Request Headers):

accept: формат ответа, здесь указано application/json — формат JSON.
authorization: ключ для вызова API, который можно выбрать после подачи заявки.

Также заданы параметры тела запроса (Request Body):

model: модель для генерации видео, основные модели: kling-v1, kling-v1-6, kling-v2-master, kling-v2-1-master, kling-v2-5-turbo, kling-v2-6, kling-v3, kling-v3-omni, kling-video-o1.
mode: режим генерации видео, возможные значения: стандартный std, ускоренный pro и нативный 4K 4k. Режим 4k поддерживается только моделями kling-v3 и kling-v3-omni и несовместим с camera_control (управление камерой).
action: тип задачи генерации видео — text2video, image2video или extend.
start_image_url: ссылка на начальное изображение, обязательна при image2video.
end_image_url: необязательная ссылка на конечное изображение при image2video.
duration: длительность видео в секундах. Модели kling-v3 и kling-v3-omni поддерживают гибкую длительность от 3 до 15 секунд (целые числа), остальные модели — 5 или 10 секунд.
generate_audio: опционально, булево значение, указывающее, нужно ли генерировать аудио. Поддерживается моделями kling-v3, kling-v3-omni и kling-v2-6 (только в режиме pro). По умолчанию false.
aspect_ratio: соотношение сторон видео, опционально, поддерживаются 16:9, 9:16, 1:1, по умолчанию 16:9.
cfg_scale: интенсивность соответствия подсказке, диапазон [0,1], чем больше, тем точнее.
camera_control: опционально, параметры управления движением камеры, поддерживаются предустановки type/simple и настройки horizontal, vertical, pan, tilt, roll, zoom.
negative_prompt: опционально, отрицательные подсказки, которых нужно избегать, максимум 200 символов.
element_list: список основных объектов, применяется только для модели kling-video-o1, подробности в официальной документации.
video_list: список референсных видео по URL, применяется только для модели kling-video-o1, подробности в официальной документации.
prompt: подсказка.
callback_url: URL для обратного вызова результата.

После выбора параметров справа автоматически сгенерируется соответствующий код, как показано на рисунке:

Нажмите кнопку «Try» для тестирования. В результате вы получите следующий ответ:

{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}

Возвращаемые поля:

success: статус задачи генерации видео.
task_id: ID задачи.
video_id: ID сгенерированного видео.
video_url: ссылка на видео.
duration: длительность видео.
state: состояние задачи.

Вы получили ссылку на видео в поле video_url и можете использовать её для доступа к сгенерированному видео Kling. Если нужно получить код для интеграции, можно скопировать сгенерированный код, например CURL:

curl -X POST 'https://api.xhuoapi.ai/v1/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v1",
  "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

Матрица возможностей моделей

Поддержка параметров различается в зависимости от модели. Ниже представлена матрица, основанная на официальной документации Kling video models. Перед вызовом проверьте, поддерживает ли комбинация model / mode / duration необходимые функции, иначе API вернёт ошибку вида model/mode/duration(...) is not supported with image_tail.

Модель	Режим	`end_image_url` (начальный/конечный кадр)	`generate_audio` (звук)	`camera_control` (управление камерой)	Примечания
`kling-v1`	std / pro	✅ только при `duration=5`	❌	✅ только при `duration=5`	`extend` не поддерживает `negative_prompt` и `cfg_scale`
`kling-v1-6`	std	❌	❌	❌	Поддержка мульти-изображений и `extend` во всех режимах
`kling-v1-6`	pro	✅	❌	❌
`kling-v2-master`	—	❌	❌	❌	Один режим, только `duration=5/10`
`kling-v2-1-master`	—	❌	❌	❌	Один режим, только `duration=5/10`
`kling-v2-5-turbo`	std	❌	❌	❌
`kling-v2-5-turbo`	pro	✅	❌	❌
`kling-v2-6`	std	❌	❌	❌
`kling-v2-6`	pro	✅	✅	❌	Единственная не v3 модель с поддержкой звука
`kling-v3`	std / pro	✅	✅	✅	`duration` от 3 до 15 секунд
`kling-v3`	4k	✅	✅	❌	4K режим несовместим с управлением камерой
`kling-v3-omni`	std / pro / 4k	✅	✅	❌
`kling-video-o1`	std / pro	✅	❌	❌	Только `duration=5/10`

Особенности:

mode=4k поддерживается только моделями kling-v3 и kling-v3-omni и несовместим с camera_control.
end_image_url можно использовать только при action=image2video вместе с start_image_url. Передача только end_image_url без start_image_url отклоняется.
Модели kling-v3 и kling-v3-omni принимают любое целое значение duration от 3 до 15 секунд, остальные — только 5 или 10.
По умолчанию generate_audio равен false. Поддерживается только kling-v3, kling-v3-omni и kling-v2-6 (pro режим).

Функция расширения видео

Чтобы продолжить генерацию уже созданного видео Kling, установите параметр action в значение extend и укажите ID видео, который можно получить при базовом использовании, как показано на рисунке:

ID видео:

"video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c"

Внимание: video_id — это ID уже сгенерированного видео. Если вы не знаете, как сгенерировать видео, обратитесь к разделу базового использования.

Далее необходимо заполнить подсказку для продолжения генерации видео, указав следующие параметры:

model: модель генерации видео, например kling-v1, kling-v1-5, kling-v1-6.
mode: режим генерации — стандартный std, ускоренный pro или 4K 4k (поддерживается только kling-v3 и kling-v3-omni, несовместим с управлением камерой).
duration: длительность видео, обычно 5 или 10 секунд.
start_image_url: ссылка на начальное изображение, обязательна при image2video.
prompt: подсказка.

Пример заполнения:

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

Пример Python-кода:

import requests

url = "https://api.xhuoapi.ai/v1/kling/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "model": "kling-v1",
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "prompt": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "duration": 10
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

При запуске вы получите ответ:

{
  "success": true,
  "video_id": "bbc3b105-ac72-4de2-8390-0cb37dc7d41e",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/extendVideo/Cjil4mfBfs0AAAAAAKhr6A-0_raw_video_1.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Результат аналогичен базовому, что подтверждает успешное расширение видео.

Асинхронный обратный вызов

Поскольку генерация видео через Kling Videos Generation API занимает около 1-2 минут, длительные HTTP-запросы могут привести к излишней нагрузке на систему. Поэтому API поддерживает асинхронный обратный вызов. Процесс: клиент при запросе указывает поле callback_url. API сразу возвращает ответ с task_id — идентификатором задачи. После завершения задачи результат отправляется POST-запросом в формате JSON на указанный callback_url, включая task_id для связывания результата с задачей. Рассмотрим пример. Webhook — это сервис, принимающий HTTP-запросы. Разработчик должен заменить URL на свой сервер. Для демонстрации используется публичный сервис https://webhook.site/, где можно получить уникальный URL, например:

Скопируйте URL, например https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3, и используйте его в поле callback_url вместе с другими параметрами, как на рисунке:

При запуске вы сразу получите ответ:

{
  "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Через некоторое время на https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3 появится результат генерации видео:

Содержимое:

{
    "success": true,
    "video_id": "030bb06d-98d4-4044-9042-0aa0822e8c8c",
    "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7822108635/text2video/CjJzzGfBfqcAAAAAAKdVMQ-0_raw_video_1.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

В ответе есть поле task_id, что позволяет связать результат с задачей.

Обработка ошибок

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

400 token_mismatched: неверный запрос, возможно, отсутствуют или некорректны параметры.
400 api_not_implemented: неверный запрос, возможно, отсутствуют или некорректны параметры.
401 invalid_token: неавторизованный доступ, неверный или отсутствующий токен.
429 too_many_requests: превышен лимит запросов.
500 api_error: внутренняя ошибка сервера.

Пример ответа с ошибкой

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Заключение

В этом документе вы узнали, как использовать Kling Videos Generation API для генерации видео на основе подсказок и начальных изображений. Надеемся, что инструкция поможет вам успешно интегрировать и использовать API. Если у вас возникнут вопросы, пожалуйста, обращайтесь в нашу службу технической поддержки.

​Процесс подачи заявки

​Основное использование

​Матрица возможностей моделей

​Функция расширения видео

​Асинхронный обратный вызов

​Обработка ошибок

​Пример ответа с ошибкой

​Заключение