⌘K

Kirin Custom Elements

kirin_custom_elements

Custom Elements subject creation API for creating reusable subjects with a frontal reference image, additional reference images, and tags.

API Notes

kirin_custom_elements only supports image-based subject creation and does not support reference_type, element_image_list, element_video_list, or element_voice_id

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 for the request

Value: kirin_custom_elements

element_name string required

Subject name

Range: Up to 20 characters

element_description string required

Subject description

Range: Up to 100 characters

element_frontal_image string required

Frontal reference image used to define the main appearance of the subject. Supports an image URL or Base64-encoded image content.

Supported formats: .jpg, .jpeg, .png
Range: 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

element_refer_list array required

Additional reference image list used to define other angles or close-up details of the subject. Must include 1 to 3 images, and each image should differ from element_frontal_image.

image_url string required

Reference image URL or Base64-encoded image content.

Supported formats: .jpg, .jpeg, .png
Range: 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

tag_list array

Configure tags for the subject. One subject can have multiple tags.

tag_idName
o_101Trending Meme
o_102Character
o_103Animal
o_104Prop
o_105Clothing
o_106Scene
o_107Effect
o_108Other

tag_id string required

Tag ID.

Options: o_101, o_102, o_103, o_104, o_105, o_106, o_107, o_108

callback_url string

Callback URL

external_task_id string

Custom task ID. 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

output array

Generation results. Only present when status is completed.

content array

List of generated content

text string

Subject information JSON string containing the following fields:
element_id: Subject ID
element_name: Subject name
element_description: Subject description
element_frontal_image: Frontal reference image
element_refer_list: Additional reference image list
element_refer_list[].image_url: Reference image URL
tag_list: Tag list
tag_list[].id: Tag ID
tag_list[].name: Tag name
tag_list[].description: Tag description
owned_by: Owner user ID
final_unit_deduction: Final billing deduction

type string

Resource type, this API returns text

url string

URL (empty for this API)