⌘K

Kirin V3 Motion Control

kirin_v3_motion_control

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

Authentication

authorization string required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key.

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

model string required

Model ID used for the request

Value: kirin_v3_motion_control

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.

Polling

Since result generation takes time, you need to poll the task status after creating the task.

The initial response only returns information such as the task ID and initial status. The final result must be obtained by polling the task status endpoint using the task ID.

See the examples on the right for polling requests and responses.

Response Format

error object

Error information, only present when status is failed

code string

Error code

message string

Detailed error message

output array

Generation results, only present when status is completed

content array

List of generated resource content

type string

Resource type

Value: image｜video

url string

Processed resource URL

jobId string

Remote task ID

usage object

Usage statistics, only present when status is completed

cost string

Total cost in USD

discount number

Discount amount

metadata object

Metadata information