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

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

Натисніть кнопку «Спробувати», щоб провести тестування, як показано на малюнку, ми отримали наступний результат:

{
  "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 виглядає так:

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: тривалість відео для цього завдання, основні значення - 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": "Біла керамічна чашка для кави на глянцевому мармуровому столі з ранковим світлом з вікна. Камера повільно обертається на 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) для відповідних позицій у 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_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).

При використанні потрібно в 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" }
  ]
}'

Асинхронний зворотний виклик

Оскільки час генерації відео за допомогою 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/, відкривши цей сайт, ви отримаєте URL Webhook, як показано на малюнку:

Скопіюйте цей 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.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. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

Ідентичність

Проксі

Advanced

Kling Videos Generation API інтеграційна інструкція

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

Основне використання

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

Розширені функції відео

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

Багато зображень для посилання (`image_list`)

Асинхронний зворотний виклик

Обробка помилок

Приклад відповіді з помилкою

Висновок

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

​Основне використання

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

​Розширені функції відео

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

​Посилання на відео та редагування відео (video_list)

​Багато зображень для посилання (image_list)

​Асинхронний зворотний виклик

​Обробка помилок

​Приклад відповіді з помилкою

​Висновок

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

Основне використання

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

Розширені функції відео

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

Посилання на відео та редагування відео (`video_list`)

Багато зображень для посилання (`image_list`)

Асинхронний зворотний виклик

Обробка помилок

Приклад відповіді з помилкою

Висновок