Перейти до основного вмісту
Цей документ представить інтеграцію Kling Videos Generation API, яка дозволяє генерувати офіційні відео Kling за допомогою введення користувацьких параметрів.

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

Щоб використовувати API, спочатку потрібно перейти на сторінку Kling Videos Generation API для подачі заявки на відповідну послугу. Після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку: Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти. Після входу або реєстрації ви автоматично повернетеся на поточну сторінку. При першій подачі заявки вам буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей 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-video-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-video-o1.
  • mode: режим генерації відео, основні: стандартний режим std та режим високої швидкості pro.
  • action: дія для цього завдання генерації відео, основні три дії: створення відео з тексту (text2video), створення відео з зображення (image2video), розширення відео (extend).
  • start_image_url: при виборі дії створення відео з зображення image2video необхідно завантажити URL-адресу зображення для першого кадру.
  • end_image_url: необов’язковий для дії створення відео з зображення, вказує на останній кадр.
  • aspect_ratio: співвідношення сторін відео, необов’язкове, підтримує 16:9, 9:16, 1:1, за замовчуванням 16:9.
  • cfg_scale: сила кореляції, діапазон [0,1], чим більше, тим більше відповідності підказці.
  • camera_control: необов’язкове, параметри для контролю руху камери, підтримує типи/прості налаштування, а також горизонтальні, вертикальні, панорамні, нахил, обертання, зум тощо.
  • negative_prompt: необов’язкове, зворотні підказки, які не бажано бачити, максимум 200 символів.
  • element_list: список основних елементів, застосовується лише до моделі kling-video-o1, конкретний спосіб використання цього параметра дивіться в документації.
  • video_list: список референсних відео, отримується через URL, застосовується лише до моделі kling-video-o1, конкретний спосіб використання цього параметра дивіться в документації.
  • prompt: підказка.
  • callback_url: URL для отримання результатів.
Після вибору ви можете побачити, що праворуч також згенеровано відповідний код, як показано на малюнку:

Натисніть кнопку «Try», щоб провести тестування, як показано на малюнку, ми отримали наступний результат: 
{
  "success": true,
  "video_id": "af9a1af0-9aa0-4638-81c1-d41d6143c508",
  "video_url": "https://cdn.klingai.com/bs2/upload-kling-api/7485378259/text2video/Cjil4mfBfs0AAAAAAKbMQQ-0_raw_video_1.mp4",
  "duration": "5.1",
  "state": "succeed",
  "task_id": "e3a575aa-a4bd-49c8-9b12-cde38d5462e0"
}
У повернутому результаті є кілька полів, описаних нижче:
  • 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-v1",
  "prompt": "Білий керамічний кавовий горнятко на глянцевому мармуровому столі з ранковим світлом з вікна. Камера повільно обертається на 360 градусів навколо горнятка, зупиняючись на мить біля ручки."
}'

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

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

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

Оскільки час генерації відео за допомогою 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": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
Висновок

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