Описание интеграции Kling Videos Generation API

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

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

Чтобы использовать Kling Videos Generation API, сначала получите ваш API Token в консоли Ace Data Cloud и сохраните его для дальнейшего использования.

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

📘 Полная документация: Kling Videos Generation 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-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-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: необязательно при генерации видео из изображения, задаёт последний кадр.
duration: длительность видео, в секундах. kling-v3 и kling-v3-omni поддерживают целочисленную длительность от 3 до 15 секунд; kling-o1 поддерживает только 5 секунд; другие модели поддерживают 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 символов.
image_list: список Omni референсных изображений, применим к моделям kling-o1 и kling-v3-omni, использование описано ниже в разделе «Omni универсальный референс».
video_list: список Omni референсных видео (поддерживает редактирование видео), применим к моделям kling-o1 и kling-v3-omni, использование описано ниже в разделе «Omni универсальный референс».
prompt: промпт.
callback_url: URL, на который необходимо отправить результат обратного вызова.
async: необязательно, при установке true интерфейс немедленно возвращает task_id, без необходимости предоставлять callback_url; затем результат получается посредством опроса соответствующего интерфейса запроса задач.

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

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

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.mp4",
  "duration": "5.041",
  "state": "succeed",
  "task_id": "6c68c267-065b-4423-b66b-a0e4c59ee0d5"
}

Результат ответа содержит несколько полей, описание которых приведено ниже:

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

Можно увидеть, что мы получили удовлетворительную информацию о видео; нам нужно лишь получить сгенерированное видео Kling по адресу ссылки на видео data в результате. Кроме того, если вы хотите сгенерировать соответствующий код интеграции, его можно скопировать напрямую, например, код CURL выглядит следующим образом:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-v3",
  "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 необходимые вам функции, иначе будут возвращены ошибки вроде 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-o1`	std / pro	✅	❌	❌	Поддерживает только `duration=5`

Примечания:

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

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

Если вы хотите продолжить генерацию уже созданного видео Kling, можно установить параметр action в значение extend и ввести ID видео, которое нужно продолжить генерировать. 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.acedata.cloud/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.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
  "duration": "9.6",
  "state": "succeed",
  "task_id": "3ece87e6-3ee3-4f5e-bd70-5ae5eca89a23"
}

Можно увидеть, что содержимое результата совпадает с описанным выше, тем самым реализуется функция расширения видео.

Универсальные ссылки Omni（редактирование видео / эталонное видео / ссылка на несколько изображений）

kling-o1 и kling-v3-omni — две независимые модели, обе поддерживают возможности «универсальных ссылок». На основе генерации видео по тексту（action=text2video）можно дополнительно передавать эталонные изображения или эталонные видео, реализуя ссылки на несколько изображений, эталонные видео, а также прямое редактирование существующих видео. Основное соглашение：эталонные материалы должны быть указаны в prompt в виде <<<image_1>>>、<<<video_1>>>（нумерация начинается с 1）для ссылки на материалы в соответствующих позициях image_list / video_list, только тогда модель применит эти ссылки. Если передать только материалы, но не ссылаться на них в подсказке, материалы будут проигнорированы.

Примечание по безопасности: текущий API не предоставляет element_list. ID Kling Element Library не изолированы между арендаторами, поэтому до предоставления API управления элементами с изоляцией арендаторов используйте image_list для передачи эталонных изображений субъектов.

Omni-запросы не поддерживают negative_prompt、cfg_scale или camera_control, а также не могут использовать mode=4k. При включении эталонного видео generate_audio должен иметь значение false. video_list используется для передачи референсных видео и является наиболее распространённым сценарием этой возможности; поля элементов массива следующие:

video_url: ссылка на референсное видео, не может быть пустой. Не более 1 видео MP4/MOV, размер файла ≤200MB, частота кадров 24–60fps. Для kling-o1 требуется длительность 3–10 секунд, ширина и высота по 700–2160px; для kling-v3-omni требуется длительность 3–15.5 секунд, ширина и высота по 700–4553px, общее количество пикселей ≤8,294,400, соотношение сторон 0.4–2.
refer_type: тип референса, можно выбрать base (по умолчанию, базовое видео для редактирования, то есть «непосредственное редактирование видео», можно добавлять/удалять/изменять элементы, менять композицию, стиль, цвет, погоду и т. д.) или feature (референс характеристик, использование его стиля / движения камеры / продолжение съёмки следующего кадра).
keep_original_sound: сохранять ли аудио исходного видео, можно выбрать yes (сохранить) или no (удалить).

Примечание: при наличии референсного видео generate_audio должен быть false. Для видео с refer_type=base нельзя дополнительно указывать первый кадр / последний кадр.

Пример CURL для редактирования существующего видео (изменение видео на стиль аниме) приведён ниже:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "把 <<<video_1>>> 改成电影级动漫风格，保留原有的运动和构图",
  "video_list": [
    {
      "video_url": "https://cdn.acedata.cloud/your-reference-video.mp4",
      "refer_type": "base",
      "keep_original_sound": "no"
    }
  ]
}'

Референс по нескольким изображениям (`image_list`)

image_list используется для передачи референсных изображений (элементы / сцены / стили и т. д.); поля элементов массива следующие:

image_url: ссылка на референсное изображение, не может быть пустой. Требования: формат .jpg/.jpeg/.png; размер файла ≤10MB; наименьшая сторона ≥300px; соотношение сторон 1:2.5 ~ 2.5:1.
type: необязательно. Если не передаётся, используется как обычное референсное изображение; при передаче first_frame / end_frame используется соответственно как первый кадр / последний кадр (эквивалентно start_image_url / end_image_url).

При использовании необходимо ссылаться в prompt через <<<image_1>>>, <<<image_2>>>. Ограничение по количеству: при отсутствии референсного видео референсных изображений ≤ 7; при наличии референсного видео референсных изображений ≤ 4. При передаче только первого / последнего кадра также можно напрямую использовать start_image_url / end_image_url, но последний кадр обязательно должен использоваться вместе с первым кадром.

Примечание: если одновременно передаются start_image_url / end_image_url и image_list, первый / последний кадры будут расположены перед image_list, что может повлиять на соответствие нумерации <<<image_N>>>. Рекомендуется выбрать один из двух вариантов: если нужны первый / последний кадры, укажите type напрямую в image_list, не смешивайте с start_image_url / end_image_url.

Пример CURL генерации видео с референсом по нескольким изображениям:

curl -X POST 'https://api.acedata.cloud/kling/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "text2video",
  "model": "kling-o1",
  "mode": "std",
  "duration": 5,
  "prompt": "让 <<<image_1>>> 里的人物站在 <<<image_2>>> 的场景中，电影感光线",
  "image_list": [
    { "image_url": "https://cdn.acedata.cloud/subject.png" },
    { "image_url": "https://cdn.acedata.cloud/scene.png" }
  ]
}'

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

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

Скопируйте этот URL, после чего его можно использовать как Webhook; пример здесь: https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Далее можно задать для поля callback_url указанный выше Webhook 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.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4",
    "duration": "5.1",
    "state": "succeed",
    "task_id": "20068983-0cc9-4c6a-aeb6-9c6a3c668be0"
}

Можно увидеть, что в результате есть поле task_id; остальные поля аналогичны описанным выше, и через это поле можно реализовать связь задач.

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

При вызове API, если возникает ошибка, 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. Если у вас возникнут какие-либо вопросы, пожалуйста, свяжитесь с нашей командой технической поддержки в любое время.

Kling 3.0 Turbo

model="kling-v3-turbo" поддерживает генерацию видео по тексту и генерацию видео по изображению первого кадра, с длительностью целым числом от 3 до 15 секунд. mode="std" выводит 720p, mode="pro" выводит 1080p. Эта модель имеет встроенное нативное аудио и не предоставляет переключателя для его отключения; опустите generate_audio или установите его в true. Эта модель не поддерживает последний кадр, объекты движения камеры, отдельные негативные подсказки или cfg_scale. Пожалуйста, непосредственно опишите в prompt содержимое, которое необходимо или следует избегать.

Многосценовые видео

kling-v3 и kling-v3-omni поддерживают multi_shot=true. shot_type="intelligence" автоматически разбивает на сцены на основе prompt; shot_type="customize" предоставляет 1–6 сцен через multi_prompt, где каждый элемент содержит последовательно возрастающий от 1 index, prompt длиной не более 512 символов и целочисленный duration не менее 1 секунды. Сумма длительностей всех сцен должна быть равна общей duration. Пользовательские сцены не используют глобальный prompt. Многосценовые видео тарифицируются в соответствии с выбранной моделью, качеством изображения, конфигурацией аудио и общей длительностью.

Начало работы

AI Чат

AI Изображение

AI Видео

AI Аудио

Веб и данные

CAPTCHA

Идентичность

Coding

Другие руководства

Описание интеграции Kling Videos Generation API

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

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

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

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

Универсальные ссылки Omni（редактирование видео / эталонное видео / ссылка на несколько изображений）

Референс по нескольким изображениям (`image_list`)

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

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

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

Заключение

Kling 3.0 Turbo

Многосценовые видео

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

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

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

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

​Универсальные ссылки Omni（редактирование видео / эталонное видео / ссылка на несколько изображений）

​Эталонное видео и редактирование видео（video_list）

​Референс по нескольким изображениям (image_list)

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

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

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

​Заключение

​Kling 3.0 Turbo

​Многосценовые видео

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

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

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

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

Универсальные ссылки Omni（редактирование видео / эталонное видео / ссылка на несколько изображений）

Эталонное видео и редактирование видео（`video_list`）

Референс по нескольким изображениям (`image_list`)

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

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

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

Заключение

Kling 3.0 Turbo

Многосценовые видео