> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Инструкция по интеграции API генерации видео Kling > Kling video generation API guide - Ace Data Cloud В этой статье будет представлена инструкция по интеграции API генерации видео Kling, который позволяет создавать официальные видео Kling, вводя пользовательские параметры. ## Процесс подачи заявки Чтобы использовать API генерации видео Kling, сначала перейдите в [консоль Ace Data Cloud](https://platform.acedata.cloud/console/applications), чтобы получить ваш API Token и сохранить его для дальнейшего использования. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти. После завершения вы будете автоматически возвращены на текущую страницу. **Один API Token позволяет вызывать все сервисы платформы, не нужно отдельно запрашивать для каждого сервиса.** При первой подаче заявки предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в [консоли](https://platform.acedata.cloud/console/coin). > 📘 Полная документация: [Kling Videos Generation API →](https://platform.acedata.cloud/documents/kling-videos) ## Основное использование Сначала ознакомьтесь с основным способом использования, который включает ввод подсказки `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`, затем через соответствующий интерфейс запроса задач можно опрашивать для получения результата. После выбора вы также можете увидеть сгенерированный код справа, как показано на изображении:

Нажмите кнопку «Попробовать», чтобы протестировать, как показано на изображении, и мы получили следующий результат: ```json theme={null} { "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 будет следующим: ```shell theme={null} 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](https://app.klingai.com/global/dev/document-api/apiReference/model/videoModels), перед вызовом проверьте, поддерживает ли текущая комбинация `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: ```python theme={null} 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) ``` Нажав "Запустить", вы можете увидеть результат, как показано ниже: ```json theme={null} { "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` в формате `<<>>`, `<<>>` (нумерация начинается с 1), чтобы модель могла применить эти ссылки. Если передать только материалы, не указав их в подсказке, они будут проигнорированы. > Примечание по безопасности: текущий API не открывает `element_list`. ID библиотеки элементов Kling принадлежат пространству имен учетной записи поставщика, до предоставления API управления элементами с изоляцией арендаторов, клиентам следует использовать `image_list` для передачи основных ссылок на изображения. Запрос Omni не поддерживает `negative_prompt`, `cfg_scale` или `camera_control`, и не может использовать `mode=4k`. Если включено видео-ссылка, `generate_audio` должно быть `false`. ### Список видео и видеомонтаж (`video_list`) `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 для редактирования существующего видео (изменение видео на аниме стиль) приведен ниже: ```shell theme={null} 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_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`. Ограничение по количеству: если нет参考视频, количество参考изображений ≤ 7; если есть参考视频, количество参考изображений ≤ 4. При передаче только начального / конечного кадра также можно использовать `start_image_url` / `end_image_url`, но конечный кадр должен использоваться вместе с начальным. > Внимание: если одновременно передаются `start_image_url` / `end_image_url` и `image_list`, начальный / конечный кадр будет располагаться перед `image_list`, что может повлиять на соответствие индексов `<<>>`. Рекомендуется выбрать один из вариантов: если нужны начальный / конечный кадры, указывать их непосредственно в `image_list` с помощью `type`, не смешивая с `start_image_url` / `end_image_url`. Пример CURL для генерации видео с множественными изображениями参考: ```shell theme={null} 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_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/](https://webhook.site/), открыв этот сайт, вы получите URL Webhook, как показано на изображении: ![](https://cdn.acedata.cloud/tbcnai.png) Скопируйте этот 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`, как показано на изображении: ![](https://cdn.acedata.cloud/zv5u2q.png) Содержимое следующее: ```json theme={null} { "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`：Внутренняя ошибка сервера, что-то пошло не так на сервере. ### Пример ответа об ошибке ```json theme={null} { "success": false, "error": { "code": "api_error", "message": "не удалось получить данные" }, "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89" } ``` ## Заключение С помощью этого документа вы узнали, как использовать API генерации видео Kling, который позволяет генерировать видео на основе введенных подсказок и изображения первого кадра. Надеемся, что этот документ поможет вам лучше интегрировать и использовать данный API. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.