Створення завдання Kling Motion Control

POST

kling

videos

motion-control

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

Використовуйте цей endpoint, щоб створити завдання Motion Control із зображення персонажа та еталонного відео.

На цій сторінці описано сумісний маршрут Motion Control. Kling Video 3.0 Motion Control використовує окремий контракт API.

Обов’язкові медіафайли

image_url приймає загальнодоступну URL-адресу або необроблений рядок Base64.

Використовуйте зображення JPG, JPEG або PNG розміром не більше 10 МБ.
Установіть для кожного виміру зображення від 300 до 65 536 пікселів.
Використовуйте співвідношення сторін від 1:2,5 до 2,5:1.
Надсилайте Base64 як необроблений закодований рядок без data:image/...;base64, префікса.
Показуйте одного нічим не закритого персонажа з кадруванням тіла, що відповідає руху в еталонному відео.

video_url приймає загальнодоступну URL-адресу MP4 або MOV.

Використовуйте відео розміром не більше 100 МБ.
Установіть коротку сторону щонайменше 340 пікселів.
Установіть довгу сторону не більше 3850 пікселів.
Використовуйте безперервний кадр з одним видимим персонажем.
Уникайте монтажних склейок, змін камери та надто швидкого руху.

Дотримуйтеся обмежень тривалості та перевіряйте вкладене термінальне task_status. Зовнішній HTTP 200 або відповідь code: 0 підтверджує відповідь на запит, а не успішний результат генерації.

Установіть значення орієнтації

character_orientation є обов’язковим і приймає image або video.

Значення	Тривалість еталонного відео
`image`	3–10 секунд
`video`	3–30 секунд

Якщо ви використовуєте element_list, установіть для character_orientation значення video.

Виберіть модель і режим

Сумісний маршрут приймає kling-v2-6 і kling-v3. Обидва значення моделі приймають обидва значення режиму:

Модель	`std`	`pro`
`kling-v2-6`	Приймається	Приймається
`kling-v3`	Приймається	Приймається

Якщо не вказати model_name, запит використовує kling-v2-6. Якщо не вказати mode, запит використовує std. Значення kling-v3 зберігає форму сумісного запиту, описану на цій сторінці; воно не вибирає окремий контракт Kling 3.0 з версією у шляху запиту. Сумісний контракт не гарантує фіксовану вихідну роздільну здатність. Перевіряйте кожне повернуте відео, якщо ваш застосунок потребує певних розмірів. keep_original_sound приймає yes або no. Якщо не вказати це поле, запит використовує yes.

Потік завдання

Надішліть запит Motion Control

Надішліть вихідне зображення, еталонне відео та значення орієнтації. Виберіть модель, режим і значення звуку або використовуйте їхні задокументовані значення за замовчуванням. Збережіть повернений task_id.

Опитуйте завдання

Використовуйте Отримання завдання Kling із поверненим task_id. Продовжуйте, доки статус не стане succeed або failed.

Збережіть результат

Негайно завантажте й збережіть результат. Документація сумісного API Kling зазначає, що згенеровані відео видаляються через 30 днів. Не покладайтеся на те, що повернена URL-адреса залишатиметься доступною всі 30 днів.

Необов’язкові поля

Поле	Структура	Обмеження
`prompt`	Рядок, максимум 2500 символів	Необов’язкове текстове поле в сумісній структурі запиту.
`callback_url`	Рядок URI або порожній рядок	Не вказуйте поле або використовуйте порожній рядок, якщо URI зворотного виклику не налаштовано.
`external_task_id`	Рядок, унікальний для вашого облікового запису	Пов’язує завдання з вашим застосунком. Воно не замінює повернений `task_id` для запитів CometAPI.
`element_list`	Масив, що містить не більше одного об’єкта `{"element_id": 123}`	Поєднуйте це поле лише з `character_orientation: "video"`.
`watermark_info`	`{"enabled": boolean}`	Сумісна структура водяного знака містить лише логічне значення `enabled`.

Структура зворотного виклику

Схема зворотного виклику Legacy має таку структуру:

{
  "task_id": "<task_id>",
  "task_status": "succeed",
  "task_status_msg": "",
  "created_at": 1785398400000,
  "updated_at": 1785398460000,
  "final_unit_deduction": "<value>",
  "final_balance_deduction": {
    "quota": "<value>",
    "list_price": "<value>"
  },
  "task_info": {
    "external_task_id": "<your_unique_id>"
  },
  "task_result": {
    "videos": [
      {
        "id": "<video_id>",
        "url": "https://media.example.com/<file_id>.mp4",
        "duration": "6.4"
      }
    ]
  }
}

Статус зворотного виклику може бути submitted, processing, succeed або failed. Поля термінального результату наявні лише тоді, коли їх повернено для термінального стану.

Поля результату

Поле	Тип	Опис
`task_result.videos[].id`	Рядок	Ідентифікатор згенерованого відео.
`task_result.videos[].url`	Рядок URI	URL-адреса для отримання згенерованого відео.
`task_result.videos[].watermark_url`	Рядок URI	URL-адреса для отримання відео з водяним знаком, якщо завдання її повертає.
`task_result.videos[].duration`	Рядок	Тривалість згенерованого відео в секундах.
`final_unit_deduction`	Рядок	Остаточне значення списання одиниць, повернене із завданням.
`final_balance_deduction`	`{"quota": string, "list_price": string}`	Остаточні значення списання балансу, повернені із завданням.

Статус завдання: submitted, processing, succeed або failed.

Дивіться довідник API Kling Motion Control і протокол зворотного виклику Kling щоб дізнатися деталі API.

Авторизації

Authorization

string

header

обов'язково

Bearer authentication. Use your CometAPI API key.

Тіло

application/json

image_url

string

обов'язково

Character image as a public URL or a raw Base64 string. Send raw Base64 without a data:image/...;base64, prefix; data-URI input is outside the compatible contract. Supported formats are JPG, JPEG, and PNG. The image must be 10 MB or smaller. Its width and height must each be from 300 through 65,536 pixels, and its aspect ratio must be between 1:2.5 and 2.5:1.

video_url

string<uri>

обов'язково

Public reference motion video URL. Use an MP4 or MOV file that is 100 MB or smaller. The short edge must be at least 340 pixels, and the long edge must not exceed 3850 pixels. The video must be at least 3 seconds long. The maximum duration depends on character_orientation.

character_orientation

enum<string>

обов'язково

Required compatible string enum. With image, the reference video can be 3 to 10 seconds long. With video, the reference video can be 3 to 30 seconds long.

Доступні опції:

image,

video

model_name

enum<string>

за замовчуванням:kling-v2-6

Model ID for this compatible Motion Control request. Omit this field to use kling-v2-6. The kling-v3 value keeps this compatible request shape; it does not select the separate Kling 3.0 path-version contract.

Доступні опції:

kling-v2-6,

kling-v3

prompt

string

Optional text field in the compatible request structure. Maximum 2500 characters.

Maximum string length: 2500

keep_original_sound

enum<string>

за замовчуванням:yes

Compatible string enum. Accepted values are yes and no. Omitted requests use yes.

Доступні опції:

yes,

no

mode

enum<string>

за замовчуванням:std

Both compatible models accept std and pro. Omitted requests use std.

Доступні опції:

std,

pro

callback_url

Optional callback field in the compatible structure. Provide a URI, or omit the field or send an empty string when no callback URI is configured.

external_task_id

string

Optional ID for correlation in your application. The value must be unique for your account. Store the returned task_id for CometAPI status queries.

element_list

object[]

Optional compatible Element structure. Provide at most one object, and combine this field only with character_orientation: video.

Maximum array length: 1

Show child attributes

watermark_info

object

Optional compatible watermark structure.

Show child attributes

Відповідь

200 - application/json

Task accepted.

code

integer

обов'язково

Response code. A value of 0 indicates that the request was accepted.

message

string

обов'язково

Response message.

data

object

обов'язково

Show child attributes

Останнє оновлення 31 липня 2026 р.

curl https://api.cometapi.com/kling/v1/videos/motion-control \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-v3",
    "image_url": "https://your-image-host.example.com/character.png",
    "video_url": "https://your-video-host.example.com/reference-motion.mp4",
    "prompt": "Studio scene.",
    "keep_original_sound": "no",
    "character_orientation": "video",
    "mode": "std"
  }'

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "<task_id>",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1785398400000,
    "updated_at": 1785398400000
  }
}

Модерація контенту

API-ключі

Створення завдання Kling Motion Control

Обов’язкові медіафайли

Установіть значення орієнтації

Виберіть модель і режим

Потік завдання

Необов’язкові поля

Структура зворотного виклику

Поля результату

Авторизації

Тіло

Відповідь

​Обов’язкові медіафайли

​Установіть значення орієнтації

​Виберіть модель і режим

​Потік завдання

​Необов’язкові поля

​Структура зворотного виклику

​Поля результату

Авторизації

Тіло

Відповідь

Обов’язкові медіафайли

Установіть значення орієнтації

Виберіть модель і режим

Потік завдання

Необов’язкові поля

Структура зворотного виклику

Поля результату