Kling V3 Motion Control

kling-v3-motion-control

V3 Action control video generation: Creating action control videos by using images and reference videos.

Endpoints

POST /v1/queue/kling-v3-motion-control # Create task

GET /v1/queue/kling-v3-motion-control/requests/{request_id}/status # Check status

GET /v1/queue/kling-v3-motion-control/requests/{request_id}/response # Get result

PUT /v1/queue/kling-v3-motion-control/requests/{request_id}/cancel # Cancel task

Request parameters

curl --request 'POST' 'https://odirouter.ai/model/v1/queue/kling-v3-motion-control' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --location \
  --data-raw '{
  "image_url": "https://www.gstatic.com/webp/gallery/3.jpg",
  "video_url": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "character_orientation": "image",
  "mode": "std",
  "prompt": "A person dancing gracefully",
  "keep_original_sound": "yes"
}'

prompt string

Text prompt. Can include positive and negative descriptions to add elements or achieve camera effects.

Note: Must not exceed 2500 characters

image_url string required

Reference image. The characters, background, and other elements in the generated video are based on this image.

Image requirements:

Supports image Base64 encoding or image URL (must be publicly accessible)

Note: When using Base64, do not add any prefix (e.g. data:image/png;base64,) before the Base64 string — pass the raw Base64-encoded string directly

Supported formats: .jpg / .jpeg / .png

File size must not exceed 10MB; image dimensions between 300px and 65536px; aspect ratio between 1:2.5 and 2.5:1

Content requirements:

Character proportions should match those in the reference action video as closely as possible; avoid driving a half-body character with full-body actions

Characters must have their upper body or full body (limbs and head) clearly visible without obstruction

Avoid extreme orientations such as upside-down or lying flat; character should occupy a sufficient portion of the frame

Supports realistic and stylized characters (including humans, humanoid animals, some pure animals, and characters with humanoid body proportions)

video_url string required

URL of the reference video. The character's actions in the generated video will follow this reference.

Video requirements:

Supported formats: .mp4 / .mov; file size must not exceed 100MB; both width and height must be between 340px and 3850px

Minimum duration: 3 seconds

When character_orientation is image: maximum duration is 10 seconds

When character_orientation is video: maximum duration is 30 seconds

Content requirements:

Characters must have their upper body or full body (all limbs and head) clearly visible without obstruction

Recommended to upload single-person action videos; for 2 or more people, the character with the largest presence in the frame will be used

Recommended to use real human actions; some stylized characters with humanoid proportions are also supported

The video should be a single continuous shot with the character always in frame; avoid cuts or camera movements

Avoid overly fast actions; smoother actions produce better results

element_list array

Subject reference list based on subject IDs from the subject library. Currently supports up to 1 subject.

For creating subjects, see: kirin_custom_elements

"element_list": [

{ "element_id": 829836802793406551 }

]

Note: When using subjects, the generated video can only follow the character orientation from the reference video.

element_id long required

Subject ID from the subject library

keep_original_sound string

Whether to retain the original sound from the reference video

Default: yes

Options: yes, no

character_orientation string required

Orientation of the character in the generated video

Options:

image: Match the character orientation in the reference image; reference video must not exceed 10 seconds

video: Match the character orientation in the reference video; reference video must not exceed 30 seconds

Note: When using subjects, the generated video can only follow the character orientation from the reference video.

mode string required

Generation mode

Options:

std: Standard mode — basic mode with high cost-efficiency

pro: Pro mode (high quality) — high-performance mode with better video quality

watermark_info object

Whether to generate a watermarked version of the result. Custom watermarks are not supported.

enabled boolean

true: Generate a watermarked version

false: Do not generate a watermarked version

callback_url string

Callback URL

external_task_id string

Custom task ID

A user-defined task ID. It does not override the system-generated task ID but can be used to query the task.

Note: Must be unique per user.

Response parameters

{
  "request_id": "task_01hxyz...",
  "response_url": "https://odirouter.ai/model/v1/queue/kling-v3-motion-control/requests/task_01hxyz.../response",
  "status_url": "https://odirouter.ai/model/v1/queue/kling-v3-motion-control/requests/task_01hxyz.../status",
  "cancel_url": "https://odirouter.ai/model/v1/queue/kling-v3-motion-control/requests/task_01hxyz.../cancel",
  "queue_position": 0
}

Field	Type	Description
`request_id`	string	Task ID used for all follow-up operations.
`response_url`	string	URL to fetch the final result.
`status_url`	string	URL to query task status.
`cancel_url`	string	URL to cancel the task.
`queue_position`	int	Current queue position.

Follow-up operations

Check status

Get result

Cancel task

Error handling