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

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

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

Чтобы использовать API генерации видео Kling, сначала перейдите в консоль 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://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"
}

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

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

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

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

Запрос Omni не поддерживает negative_prompt, cfg_scale или camera_control, и не может использовать mode=4k. Если включено видео-ссылка, generate_audio должно быть false. video_list используется для передачи ссылок на参考视频, это наиболее распространенный сценарий использования данной функции, поля элементов массива следующие:

video_url：Ссылка на参考视频, не может быть пустой. Требования: формат MP4/MOV; разрешение 720px–2160px; длительность 3–10 секунд; частота кадров 24–60fps; размер файла ≤200MB; максимум 1 видео.
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).

При использовании необходимо ссылаться на <<<image_1>>>, <<<image_2>>> в prompt. Ограничение по количеству: если нет参考视频, количество参考изображений ≤ 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/, открыв этот сайт, вы получите URL Webhook, как показано на изображении:

Скопируйте этот URL, и вы сможете использовать его в качестве Webhook, пример здесь: https://webhook.site/624b2c78-6dbd-4618-9d2b-b32eade6d8c3. Далее мы можем установить поле callback_url на указанный выше URL Webhook, одновременно заполнив соответствующие параметры, конкретное содержание показано на изображении:

Нажмите “Запустить”, и вы сразу получите результат, как показано ниже:

{
  "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, если возникает ошибка, 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

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

Прокси

Продвинутый

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

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

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

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

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

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

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

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

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

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

Заключение

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

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

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

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

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

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

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

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

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

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

​Заключение

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

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

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

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

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

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

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

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

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

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

Заключение