> ## 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. # Kling Videos Generation API інтеграційна інструкція > Kling video generation API guide - Ace Data Cloud Цей документ представить інтеграційну інструкцію для Kling Videos Generation API, яка дозволяє генерувати офіційні відео Kling за допомогою введення користувацьких параметрів. ## Процес подачі заявки Щоб використовувати Kling Videos Generation API, спочатку перейдіть до [консолі 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` необхідно завантажити URL-адресу зображення для першого кадру. * `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`: необов'язкове, параметри для контролю руху камери, підтримує типи/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`, URL-адреса відео для цього завдання генерації. * `duration`, тривалість відео для цього завдання генерації. * `state`, статус завдання генерації відео. Ми отримали задовільну інформацію про відео, нам потрібно лише отримати згенероване відео Kling за URL-адресою, вказаною в результаті `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`: тривалість відео для цього завдання, основні значення - 5с та 10с. * `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) для відповідних позицій у `image_list` / `video_list`, щоб модель могла застосувати ці посилання. Якщо передати лише матеріали, не посилаючись на них у підказці, матеріали будуть проігноровані. > Інформація про безпеку: поточний API не відкриває `element_list`. Вгору ID бібліотеки Kling Element належать простору імен облікового запису постачальника, до надання 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" } ] }' ``` ## Асинхронний зворотний виклик Оскільки час генерації відео за допомогою Kling Videos Generation API відносно довгий, приблизно 1-2 хвилини, якщо API довго не відповідає, HTTP запит буде підтримувати з'єднання, що призводить до додаткових витрат системних ресурсів, тому цей API також підтримує асинхронний зворотний виклик. Загальний процес: коли клієнт ініціює запит, додатково вказується поле `callback_url`, після ініціації API запит повертає результат, що містить поле `task_id`, яке представляє поточний 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` на вказаний Webhook URL, одночасно заповнивши відповідні параметри, конкретний зміст, як показано на малюнку:

Натиснувши "Запустити", ви відразу отримаєте результат, як показано нижче: ``` { "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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.