Create a Kling Motion Control task

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
  }
}

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

Submit the Motion Control request

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.

Poll the task

Use Get a Kling task with the returned task_id. Continue until the status is succeed or failed.

Store the result

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:

{
  "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"
      }
    ]
  }
}

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 and Kling callback protocol for API details.

Authorizations

Authorization

string

header

required

Bearer authentication. Use your CometAPI API key.

Body

application/json

image_url

string

required

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>

required

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

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.

Available options:

image,

video

model_name

enum<string>

default: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.

Available options:

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>

default:yes

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

Available options:

yes,

no

mode

enum<string>

default:std

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

Available options:

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

Response

200 - application/json

Task accepted.

code

integer

required

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

message

string

required

Response message.

data

object

required

Show child attributes

Create a Kling image-to-video task

Create a Kling multi-image video task

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
  }
}

Content moderation

API keys

Required media

Set the orientation value

Choose the model and mode

Task flow

Optional fields

Callback structure

Result fields

Authorizations

Body

Response

​Required media

​Set the orientation value

​Choose the model and mode

​Task flow

​Optional fields

​Callback structure

​Result fields

Authorizations

Body

Response

Required media

Set the orientation value

Choose the model and mode

Task flow

Optional fields

Callback structure

Result fields