⌘K

Kirin V2.1 - Reference to Image

kirin_v2_1_reference2image

Kirin V2.1 reference-to-image generation uses multiple reference images for subject, scene, and style control to produce a new image.

API Notes

kirin_v2_1_reference2image supports 1 to 4 subject reference images through subject_image_list, and optionally supports scene_image and style_image

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_v2_1_reference2image

prompt string

Positive text prompt.

Must not exceed 2500 characters.

subject_image_list array required

Subject reference image list. Supports 1 to 4 images, each passed through a key:value object as shown below:

"subject_image_list": [
  { "subject_image": "image_url_or_base64" },
  { "subject_image": "image_url_or_base64" },
  { "subject_image": "image_url_or_base64" },
  { "subject_image": "image_url_or_base64" }
]

The API does not apply any cropping. Upload images with the subject already prepared as intended
Supports Base64 encoded images or image URLs (must be publicly accessible)
Note: when using Base64, do not add any prefix such as data:image/png;base64,; pass the raw Base64 string directly
Correct Base64 example: iVBORw0KGgoAAAANSUhEUgAAAAUA...
Incorrect Base64 example with a prefix: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
Supported formats: .jpg / .jpeg / .png
File size must not exceed 10MB; width and height must be at least 300px; aspect ratio must be between 1:2.5 and 2.5:1

subject_image string required

Subject image URL or raw Base64 string

scene_image string

Optional scene reference image.

Supports Base64 encoded images or image URLs (must be publicly accessible)
Note: when using Base64, do not add any prefix such as data:image/png;base64,; pass the raw Base64 string directly
Correct Base64 example: iVBORw0KGgoAAAANSUhEUgAAAAUA...
Incorrect Base64 example with a prefix: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
Supported formats: .jpg / .jpeg / .png
File size must not exceed 10MB; width and height must be at least 300px; aspect ratio must be between 1:2.5 and 2.5:1

style_image string

Optional style reference image.

Supports Base64 encoded images or image URLs (must be publicly accessible)
Note: when using Base64, do not add any prefix such as data:image/png;base64,; pass the raw Base64 string directly
Correct Base64 example: iVBORw0KGgoAAAANSUhEUgAAAAUA...
Incorrect Base64 example with a prefix: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
Supported formats: .jpg / .jpeg / .png
File size must not exceed 10MB; width and height must be at least 300px; aspect ratio must be between 1:2.5 and 2.5:1

n integer

Number of images to generate.

Default: 1

Range: 1 - 9

aspect_ratio string

Aspect ratio of the generated image (width:height).

Default: 16:9

Options: 16:9, 9:16, 1:1, 4:3, 3:4, 3:2, 2:3, 21:9

watermark_info object

Whether to generate a watermarked result at the same time. Custom watermarks are not supported.

enabled boolean

true: Generate a watermarked result
false: Do not generate a watermarked result

callback_url string

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

The notification message schema follows the callback protocol.

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: it 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. Use this field for programmatic failure handling.

error_message string

Detailed error message describing why the task failed.

output array

Generation results. Only present when status is completed.

content array

List of generated content.

type string

Resource type, such as image or video.

url string

Generated resource URL.

usage object

Usage statistics. Only present when status is completed.

cost string

Total cost in USD.

discount number

Discount amount.