Kirin V1 - Image to Video

API Notes

kirin_v1_i2v does not support only tail frame (image_tail only)

kirin_v1_i2v only supports first and last frame (image + image_tail) when duration is 5 seconds

kirin_v1_i2v only supports motion brush (dynamic_masks/static_mask) when duration is 5 seconds

kirin_v1_i2v generates videos at 720p resolution with 30fps frame rate for both std and pro modes

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_v1_i2v

---

image string required

Reference image. Supports Base64 encoded image or image URL (ensure accessibility)

If using Base64, ensure all image data parameters are Base64 encoded strings without prefixes like data:image/png;base64,. The correct format should be the Base64 encoded string directly

Image requirements:
Format: .jpg / .jpeg / .png
File size: max 10MB
Dimensions: min 300px width and height
Aspect ratio: between 1:2.5 ~ 2.5:1

image and image_tail parameters must have at least one, both cannot be empty
image + image_tail parameters and dynamic_masks/static_mask parameters are mutually exclusive, cannot be used together

---

image_tail string

Reference image - tail frame control. Supports Base64 encoded image or image URL (ensure accessibility)

If using Base64, ensure all image data parameters are Base64 encoded strings without prefixes like data:image/png;base64,. The correct format should be the Base64 encoded string directly. Please only provide the Base64 encoded string portion so the system can correctly process and parse your data

Image requirements:
Format: .jpg / .jpeg / .png
File size: max 10MB
Dimensions: min 300px width and height

image and image_tail parameters must have at least one, both cannot be empty

---

prompt string

Video generation prompt, length between 1-2500 characters

---

mode string

Video generation mode

std: Standard mode, basic mode, high cost-performance
pro: Expert mode (high quality), high performance mode, better generated video quality

Options: std, pro

Default: std

---

duration string

Video duration in seconds

Options: 5, 10

Default: 5

---

cfg_scale number

Freedom of generated video; larger value means less model freedom, stronger correlation with user input prompt

Range: 0 - 1

Default: 0.5

---

negative_prompt string

Negative prompt for specifying content you don’t want in the generated video, max 2500 characters

---

static_mask string

Static brush mask area (mask image painted by user through motion brush)

“Motion brush” capability includes “dynamic brush dynamic_masks” and “static brush static_mask”

Supports Base64 encoded image or image URL (ensure accessibility, format requirements same as image field)

Image requirements:
Format: .jpg / .jpeg / .png
Aspect ratio must match input image (image field), otherwise task fails
Resolution of static_mask and dynamic_masks.mask must be identical, otherwise task fails

Note: Only supported when duration is 5 seconds

---

dynamic_masks array

Dynamic brush configuration list. Can configure multiple groups (max 6), each containing “mask area mask” and “motion trajectory trajectories” sequence

Note: Only supported when duration is 5 seconds

mask string

Dynamic brush mask area (mask image painted by user through motion brush)

Supports Base64 encoded image or image URL (ensure accessibility, format requirements same as image field)

Image requirements:
Format: .jpg / .jpeg / .png
Aspect ratio must match input image (image field), otherwise task fails
Resolution of static_mask and dynamic_masks.mask must be identical, otherwise task fails

trajectories array

Motion trajectory coordinate sequence

For 5s video, trajectory length max 77, coordinate count range: [2, 77]
Trajectory coordinate system uses image bottom-left corner as origin

Note 1: More coordinate points mean more accurate trajectory; with only 2 trajectory points, it’s a straight line connecting these two points
Note 2: Trajectory direction follows input order, first coordinate is trajectory start, subsequent coordinates connect sequentially to form motion trajectory

x number

Trajectory point x-coordinate (pixel coordinate in 2D coordinate system, with input image bottom-left as origin)

y number

Trajectory point y-coordinate (pixel coordinate in 2D coordinate system, with input image bottom-left as origin)

---

watermark_info array

Whether to generate results with watermark simultaneously

Defined by enabled parameter, specific array format as follows:

"watermark_info": {
  "enabled": boolean // true for generation, false for no generation
}

Custom watermarks are not currently supported

---

callback_url string

Callback notification address for this task result. If configured, the server will actively notify when task status changes

---

external_task_id string

Custom task ID

User-defined task ID. Input will not overwrite system-generated task ID, but supports task query through this ID

Please note, must ensure uniqueness under a single user

---

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

error_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

size string

Image size

---

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
002002095	Internal generation error
002002096	Result parsing error
002002097	HTTP error response
002002098	Status check error
002002099	Task creation failed