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://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 Element не є ізольованими для орендарів, до надання 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" }
  ]
}'

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

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

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Проксі

Advanced

Coding

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

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

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

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

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

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

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

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

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

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

Висновок

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

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

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

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

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

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

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

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

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

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

​Висновок

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

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

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

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

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

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

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

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

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

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

Висновок