Kling Videos Generation API интеграция

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

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

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

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

📘 Полная документация: Kling Videos Generation API →

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

Сначала ознакомьтесь с основным способом использования, который включает ввод подсказки prompt, действия action, URL-адреса начального изображения 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, подробности приведены ниже:

Мы видим, что здесь установлены заголовки запроса, включая:

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

Также установлен тело запроса, включая:

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, затем можно опрашивать соответствующий интерфейс для получения результата.

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

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

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://platform2.cdn.acedata.cloud/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5.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": "Белая керамическая кружка с кофе на блестящем мраморном столешнице с утренним светом из окна. Камера медленно вращается на 360 градусов вокруг кружки, на мгновение останавливаясь на ручке."
}'

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

Разные модели имеют различные уровни поддержки параметров. Следующая матрица составлена на основе документации моделей видео Kling, перед вызовом проверьте, поддерживает ли текущая комбинация 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 может использоваться только с action=image2video в сочетании с start_image_url. Передача только 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: длительность видео для этой задачи генерации, в основном 5s и 10s.
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": "Белая керамическая кружка на глянцевом мраморном столе с утренним светом из окна. Камера медленно вращается на 360 градусов вокруг кружки, на мгновение останавливаясь на ручке.",
    "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://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.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 не изолированы по арендаторам, до предоставления 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>>>. Рекомендуется выбрать один из вариантов: если нужны начальный / конечный кадры, указывать их непосредственно в image_list с помощью type, не смешивая с 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" }
  ]
}'

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

Поскольку время генерации видео с помощью API Kling Videos Generation относительно долгое, примерно 1-2 минуты, если API долго не отвечает, HTTP-запрос будет поддерживать соединение, что приведет к дополнительному потреблению системных ресурсов, поэтому этот API также поддерживает асинхронные обратные вызовы. Общий процесс: когда клиент инициирует запрос, дополнительно указывается поле callback_url, после того как клиент инициирует API-запрос, API немедленно возвращает результат, содержащий поле task_id, представляющее текущий идентификатор задачи. Когда задача завершена, результат сгенерированного видео будет отправлен на указанный клиентом callback_url в формате POST JSON, в котором также будет включено поле 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://platform2.cdn.acedata.cloud/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee.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": "не удалось получить данные"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Заключение

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

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

AI Чат

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

AI Видео

AI Аудио

Веб и данные

CAPTCHA

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

Прокси

Продвинутый

Coding

Kling Videos Generation API интеграция

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

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

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

Расширенные функции видео

Omni универсальная справка (видеомонтаж / справочное видео / многоизображен справка)

Множественные изображения ( `image_list` )

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

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

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

Заключение

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

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

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

​Расширенные функции видео

​Omni универсальная справка (видеомонтаж / справочное видео / многоизображен справка)

​Справочное видео и видеомонтаж (video_list)

​Множественные изображения ( image_list )

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

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

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

​Заключение

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

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

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

Расширенные функции видео

Omni универсальная справка (видеомонтаж / справочное видео / многоизображен справка)

Справочное видео и видеомонтаж (`video_list`)

Множественные изображения ( `image_list` )

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

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

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

Заключение