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

Value: kirin_v3_image

---

prompt string required

Text prompt, can include positive and negative descriptions

Max 2500 characters

---

negative_prompt string

Negative text prompt

Max 2500 characters

It is recommended to write negative prompts as negative descriptions in the positive prompt

Note: Image-to-image (when image field is not empty) does not support negative prompts

---

image string

Reference image

Supports Base64 encoded image or image URL (ensure accessibility)

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

Base64 encoding requirements:
If using Base64 method, ensure all image data parameters are Base64 encoded. When submitting data, do not add any prefix before the Base64 encoded string, such as data:image/png;base64,. The correct parameter format should be the Base64 encoded string directly

Example:

Correct Base64 encoded parameter:

iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==

Incorrect Base64 encoded parameter (with data: prefix):

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg==

Please provide only the Base64 encoded string portion so the system can correctly process and parse your data

---

element_list array

Subject reference list, configured based on subject ID from subject library

To create a subject, refer to: kirin_custom_elements

Quantity limits:
The total number of reference subjects and reference images must not exceed 10

Format as key:value pairs:

"element_list": [
  {
    "element_id": long
  },
  {
    "element_id": long
  }
]

element_id integer

Subject ID from subject library

---

resolution string

Image generation resolution

Options: 1k, 2k

Default: 1k

---

n integer

Number of images to generate

Default: 1

Range: 1 - 9

---

aspect_ratio string

Image aspect ratio (width:height)

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

Default: 16:9

---

watermark_info array

Whether to generate results with watermarks simultaneously

Defined via the enabled parameter

Custom watermarks are not currently supported

Format as key:value pairs:

"watermark_info": {
  "enabled": boolean
}

enabled boolean

true for generation, false for no generation

---

callback_url string

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

---

external_task_id string

Custom task ID

User-defined task ID, will not overwrite the system-generated task ID when provided, but supports task query via this ID

Please note that uniqueness must be ensured under a single user

---

Polling

Since image 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., image

url string

Generated content URL

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
006001094	Task resource insufficient
006001095	Task response error
006001099	Task creation error