Інструкція з інтеграції 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, еталонне зображення першого кадру 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, конкретний вміст наведено нижче:

Можна побачити, що тут ми налаштували Request Headers, зокрема:

accept: який формат результату відповіді потрібно отримати; тут вказано application/json, тобто формат JSON.
authorization: ключ для виклику API, після подання заявки його можна безпосередньо вибрати зі спадного списку.

Також налаштовано Request Body, зокрема:

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

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

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

{
  "success": true,
  "video_id": "900798310464749610",
  "video_url": "https://cdn.acedata.cloud/assets/examples/kling/6c68c267-065b-4423-b66b-a0e4c59ee0d5-6a664a591a53.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": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle."
}'

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

Підтримка параметрів різними моделями значно відрізняється. Наведену нижче матрицю впорядковано на основі офіційної документації Kling щодо video models. Перед викликом спочатку перевірте, чи підтримує поточна комбінація 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 можна використовувати лише разом із start_image_url при action=image2video. Передавання лише 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": "White ceramic coffee mug on glossy marble countertop with morning window light. Camera slowly rotates 360 degrees around the mug, pausing briefly at the handle.",
    "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.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.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 не ізольовані між орендарями, тому до надання 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>>>. Рекомендується вибрати один із двох способів: якщо потрібні перший / останній кадри, безпосередньо вказуйте type в image_list, не змішуйте з 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-запиту API негайно повертає результат, який містить поле task_id, що представляє ID поточного завдання. Після завершення завдання результат згенерованого відео буде надіслано у формі POST JSON до callback_url, вказаного клієнтом, де також міститься поле task_id, таким чином результати завдань можна пов’язати за ID. Нижче ми на прикладі дізнаємося, як саме це зробити. Спочатку Webhook-зворотний виклик — це сервіс, який може приймати HTTP-запити, розробник має замінити його URL-адресою власноруч розгорнутого HTTP-сервера. Для зручності демонстрації тут використовується публічний вебсайт-приклад Webhook https://webhook.site/，відкривши цей вебсайт, можна отримати Webhook URL, як показано на зображенні:

Скопіювавши цей 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.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Висновок

Завдяки цьому документу ви вже дізналися, як використовувати Kling Videos Generation API для створення відео шляхом введення підказки та еталонного зображення першого кадру. Сподіваємося, цей документ допоможе вам краще інтегрувати та використовувати цей API. Якщо у вас виникнуть будь-які запитання, будь ласка, звертайтеся до нашої команди технічної підтримки в будь-який час.

Kling 3.0 Turbo

model="kling-v3-turbo" підтримує генерацію відео за текстом і генерацію відео на основі зображення першого кадру з тривалістю цілим числом від 3 до 15 секунд. mode="std" виводить 720p, mode="pro" виводить 1080p. Ця модель має вбудоване нативне аудіо й не надає перемикача для його вимкнення; не вказуйте generate_audio або встановіть його значення на true. Ця модель не підтримує останній кадр, об’єкти руху камери, окремі негативні підказки або cfg_scale. Будь ласка, безпосередньо опишіть у prompt вміст, який потрібно показати або уникнути його появи.

Багатокадрове відео

kling-v3 і kling-v3-omni підтримують multi_shot=true. shot_type="intelligence" автоматично розбиває на сцени відповідно до prompt; shot_type="customize" надає 1–6 сцен через multi_prompt, кожен елемент містить index, що безперервно зростає від 1, prompt обсягом до 512 символів і цілу duration щонайменше 1 секунду. Сума тривалостей усіх сцен має дорівнювати загальній duration. Користувацькі сцени не використовують глобальний prompt. За багатокадрове відео стягується плата відповідно до вибраної моделі, якості зображення, конфігурації аудіо та загальної тривалості.

Getting Started

AI Чат

AI Зображення

AI Відео

AI Аудіо

Веб і дані

CAPTCHA

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

Coding

Інші посібники

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

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

Базове використання

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

Функція розширення відео

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

Багатозображувальне посилання（`image_list`）

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

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

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

Висновок

Kling 3.0 Turbo

Багатокадрове відео

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

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

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

​Функція розширення відео

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

​Еталонне відео та редагування відео（video_list）

​Багатозображувальне посилання（image_list）

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

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

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

​Висновок

​Kling 3.0 Turbo

​Багатокадрове відео

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

Базове використання

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

Функція розширення відео

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

Еталонне відео та редагування відео（`video_list`）

Багатозображувальне посилання（`image_list`）

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

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

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

Висновок

Kling 3.0 Turbo

Багатокадрове відео