Kirin Motion Control

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 to use for the request.

Value: kirin_motion_control

---

image_url string required

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

Image content requirements:
Character proportions should match reference action proportions as much as possible; avoid using full-body actions to drive half-body characters
Character should show clear upper body or full body limbs and head, avoid occlusion
Avoid extreme orientations like handstands or lying flat; character should not occupy too small a portion of the frame
Supports realistic/stylized characters (including humans/humanoid animals/some pure animals/some characters with humanoid limb proportions)

Supports Base64 encoded image or image URL (ensure accessibility)

If using Base64, ensure all image data parameters are in Base64 encoding format. Do not add any prefix to the Base64 encoded string, such as data:image/png;base64,. The correct format should be the pure Base64 encoded string

Image requirements:
Format: .jpg, .jpeg, .png
File size: max 10MB
Dimensions: between 300px ~ 65536px
Aspect ratio: between 1:2.5 ~ 2.5:1

---

video_url string required

Reference video URL. The character actions in the generated video will match the reference video

Video content requirements:
Character should show clear upper body or full body with all limbs and head visible, avoid occlusion
Recommend uploading single-person action video; for 2+ people, the person occupying the largest portion will be used
Real human actions recommended; some stylized characters with humanoid limb proportions may work
Video should be continuous shot with character always in frame; avoid cuts and camera movements, otherwise video will be trimmed
Avoid overly fast movements; relatively smooth actions produce better results

Video requirements:
Format: .mp4, .mov
File size: max 100MB
Dimensions: both width and height between 340px ~ 3850px

Duration requirements:
Minimum: 3 seconds
Maximum depends on character_orientation:
When orientation matches video character: max 30 seconds
When orientation matches image character: max 10 seconds

Note: For difficult or fast actions, results may be shorter than uploaded video duration as the model only extracts valid action segments (minimum 3 seconds of continuous usable action). Credits consumed for such cases are non-refundable

---

character_orientation string required

Character orientation in the generated video, can match image or video

image: Match image character orientation; reference video duration max 10 seconds
video: Match video character orientation; reference video duration max 30 seconds

Options: image, video

---

mode string required

Video generation mode

std: Standard mode, cost-effective
pro: Expert mode (high quality), higher performance mode with better video quality

Options: std, pro

---

prompt string

Text prompt, can include positive and negative descriptions

Can be used to add elements or achieve camera movement effects in the video

Max 2500 characters

---

keep_original_sound string

Whether to keep the original audio from the reference video

yes: Keep original audio
no: Discard original audio

Options: yes, no

Default: yes

---

callback_url string

Callback notification URL for task results. If configured, the server will actively notify when task status changes

---

external_task_id string

Custom task ID

User-defined task ID that will not override the system-generated task ID but can be used for task queries

Must be unique within a single user account

---

Polling

Since video generation takes time, you need to poll the task status after creation

The initial response returns the task ID and initial status. The actual generation results must be obtained through polling the task status endpoint

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 content

type string

Resource type, e.g., video, image

url string

Generated content URL

duration number

Video duration

jobId string

Remote job 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

---

Error Codes

Error Code	Description
014002095	Internal generation error
014002096	Result parsing exception
014002097	HTTP error response
014002099	Sync generation exception