> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Kling Motion Control task
> Create a Kling Motion Control task from a character image and a reference motion video with the compatible CometAPI route.
Use this endpoint to create a Motion Control task from a character image and a
reference video.
This page describes the compatible Motion Control route. Kling Video 3.0
Motion Control uses a separate API contract.
## Required media
`image_url` accepts a public URL or a raw Base64 string.
* Use a JPG, JPEG, or PNG image that is 10 MB or smaller.
* Make each image dimension from 300 through 65,536 pixels.
* Use an aspect ratio from 1:2.5 through 2.5:1.
* Send Base64 as the raw encoded string without a
`data:image/...;base64,` prefix.
* Show one unobstructed character with body framing that matches the motion
reference.
`video_url` accepts a public MP4 or MOV URL.
* Use a video that is 100 MB or smaller.
* Make the short edge at least 340 pixels.
* Make the long edge no more than 3850 pixels.
* Use a continuous shot with one visible character.
* Avoid cuts, camera changes, and excessively fast motion.
Follow the duration limits and inspect the nested terminal `task_status`. An
outer HTTP 200 or response `code: 0` confirms the query response, not a
successful generation result.
## Set the orientation value
`character_orientation` is required and accepts `image` or `video`.
| Value | Reference video duration |
| ------- | ------------------------ |
| `image` | 3–10 seconds |
| `video` | 3–30 seconds |
If you use `element_list`, then set `character_orientation` to `video`.
## Choose the model and mode
The compatible route accepts `kling-v2-6` and `kling-v3`. Both model values
accept both mode values:
| Model | `std` | `pro` |
| ------------ | -------- | -------- |
| `kling-v2-6` | Accepted | Accepted |
| `kling-v3` | Accepted | Accepted |
If you omit `model_name`, the request uses `kling-v2-6`. If you omit `mode`,
the request uses `std`. The `kling-v3` value keeps the compatible request shape
described on this page; it does not select the separate Kling 3.0 path-version
contract.
The compatible contract does not guarantee a fixed output resolution. Inspect
each returned video if your application requires specific dimensions.
`keep_original_sound` accepts `yes` or `no`. If you omit this field, the
request uses `yes`.
## Task flow
Send the source image, reference video, and orientation value. Select a
model, mode, and sound value or use their documented defaults. Store the
returned `task_id`.
Use [Get a Kling task](./individual-queries) with the returned `task_id`.
Continue until the status is `succeed` or `failed`.
Download and store the result promptly. Kling's compatible API
documentation states that generated videos are cleared after 30 days. Do
not rely on the returned URL remaining accessible for the full 30 days.
## Optional fields
| Field | Structure | Constraint |
| ------------------ | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `prompt` | String, maximum 2500 characters | Optional text field in the compatible request structure. |
| `callback_url` | URI string or empty string | Omit the field or use an empty string when no callback URI is configured. |
| `external_task_id` | String that is unique for your account | Correlates the task with your application. It does not replace the returned `task_id` for CometAPI queries. |
| `element_list` | Array with at most one `{"element_id": 123}` object | Combine this field only with `character_orientation: "video"`. |
| `watermark_info` | `{"enabled": boolean}` | The compatible watermark structure contains only the `enabled` Boolean. |
## Callback structure
The Legacy callback schema has the following structure:
```json theme={null}
{
"task_id": "",
"task_status": "succeed",
"task_status_msg": "",
"created_at": 1785398400000,
"updated_at": 1785398460000,
"final_unit_deduction": "",
"final_balance_deduction": {
"quota": "",
"list_price": ""
},
"task_info": {
"external_task_id": ""
},
"task_result": {
"videos": [
{
"id": "",
"url": "https://media.example.com/.mp4",
"duration": "6.4"
}
]
}
}
```
The callback status can be `submitted`, `processing`, `succeed`, or `failed`.
Terminal result fields are present only when returned for the terminal state.
## Result fields
| Field | Type | Description |
| ------------------------------------ | ----------------------------------------- | --------------------------------------------------------- |
| `task_result.videos[].id` | String | Generated video ID. |
| `task_result.videos[].url` | URI string | Generated video delivery URL. |
| `task_result.videos[].watermark_url` | URI string | Watermarked video delivery URL when the task returns one. |
| `task_result.videos[].duration` | String | Generated video duration in seconds. |
| `final_unit_deduction` | String | Final unit deduction value returned with the task. |
| `final_balance_deduction` | `{"quota": string, "list_price": string}` | Final balance deduction values returned with the task. |
The task status is `submitted`, `processing`, `succeed`, or `failed`.
See the [Kling Motion Control API reference](https://kling.ai/document-api/api/video/motion-control/legacy)
and [Kling callback protocol](https://kling.ai/document-api/api/get-started/callbacks)
for API details.
## OpenAPI
````yaml api/openapi/video/kling/post-motion-control.openapi.json POST /kling/v1/videos/motion-control
openapi: 3.1.0
info:
title: Kling Motion Control API
version: 1.0.0
description: >-
Create a Kling Motion Control task from a character image and a reference
motion video.
servers:
- url: https://api.cometapi.com
security:
- bearerAuth: []
paths:
/kling/v1/videos/motion-control:
post:
summary: Create a Kling Motion Control task
description: >-
Submit a character image and a reference motion video. The response
contains a task ID that you can use for status queries.
operationId: create_kling_motion_control
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image_url
- video_url
- character_orientation
properties:
model_name:
type: string
description: >-
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.
enum:
- kling-v2-6
- kling-v3
default: kling-v2-6
image_url:
type: string
description: >-
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:
type: string
format: uri
description: >-
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`.
prompt:
type: string
maxLength: 2500
description: >-
Optional text field in the compatible request structure.
Maximum 2500 characters.
keep_original_sound:
type: string
description: >-
Compatible string enum. Accepted values are `yes` and `no`.
Omitted requests use `yes`.
enum:
- 'yes'
- 'no'
default: 'yes'
character_orientation:
type: string
description: >-
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.
enum:
- image
- video
mode:
type: string
description: >-
Both compatible models accept `std` and `pro`. Omitted
requests use `std`.
enum:
- std
- pro
default: std
callback_url:
description: >-
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.
oneOf:
- type: string
format: uri
- type: string
const: ''
external_task_id:
type: string
description: >-
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:
type: array
maxItems: 1
description: >-
Optional compatible Element structure. Provide at most one
object, and combine this field only with
`character_orientation: video`.
items:
type: object
required:
- element_id
properties:
element_id:
type: integer
format: int64
description: Kling Element ID in the compatible structure.
additionalProperties: false
watermark_info:
type: object
description: Optional compatible watermark structure.
required:
- enabled
properties:
enabled:
type: boolean
description: Boolean flag in the compatible watermark structure.
additionalProperties: false
example:
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
examples:
Image URL:
summary: Use a public character image URL
value:
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
Image base64:
summary: Use a raw Base64 character image
value:
model_name: kling-v3
image_url:
video_url: https://your-video-host.example.com/reference-motion.mp4
prompt: Studio scene.
keep_original_sound: 'no'
character_orientation: video
mode: pro
responses:
'200':
description: Task accepted.
content:
application/json:
schema:
type: object
required:
- code
- message
- data
properties:
code:
type: integer
description: >-
Response code. A value of 0 indicates that the request was
accepted.
message:
type: string
description: Response message.
data:
type: object
required:
- task_id
- task_status
- task_info
- created_at
- updated_at
properties:
task_id:
type: string
description: System-generated task ID for status queries.
task_status:
type: string
description: Task state after submission.
const: submitted
task_status_msg:
type: string
description: Status detail when returned.
task_info:
type: object
description: Additional task metadata. The object can be empty.
additionalProperties: true
created_at:
type: integer
format: int64
description: Task creation timestamp in milliseconds.
updated_at:
type: integer
format: int64
description: Last task update timestamp in milliseconds.
example:
code: 0
message: SUCCEED
data:
task_id:
task_status: submitted
task_info: {}
created_at: 1785398400000
updated_at: 1785398400000
x-codeSamples:
- lang: Shell
label: Image URL
source: |
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"
}'
- lang: Python
label: Image URL
source: |
import os
import requests
response = requests.post(
"https://api.cometapi.com/kling/v1/videos/motion-control",
headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]},
json={
"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",
},
)
result = response.json()
print(result.get("code"), result.get("data", {}).get("task_id"))
- lang: JavaScript
label: Image URL
source: |
const response = await fetch(
"https://api.cometapi.com/kling/v1/videos/motion-control",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
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",
}),
},
);
const result = await response.json();
console.log(result.code, result.data?.task_id);
- lang: Shell
label: Image base64
source: |
IMAGE_BASE64=$(openssl base64 -A -in character.png)
curl https://api.cometapi.com/kling/v1/videos/motion-control \
-H "Authorization: Bearer $COMETAPI_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <
import { readFile } from "node:fs/promises";
const imageBase64 = (await
readFile("character.png")).toString("base64");
const response = await fetch(
"https://api.cometapi.com/kling/v1/videos/motion-control",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model_name: "kling-v3",
image_url: imageBase64,
video_url: "https://your-video-host.example.com/reference-motion.mp4",
prompt: "Studio scene.",
keep_original_sound: "no",
character_orientation: "video",
mode: "pro",
}),
},
);
const result = response.json();
console.log(result.code, result.data?.task_id);
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Bearer authentication. Use your CometAPI API key.
````