⌘K

Kirin Custom Elements

kirin_custom_elements

Custom Elements entity configuration API for creating reusable entities with reference images and tags.

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

Entity name

Must not exceed 20 characters

element_description string required

Entity description

Must not exceed 100 characters

reference_type string required

Entity reference method

Options:
video_refer: Video-based entity. Entity appearance is defined by element_video_list.
image_refer: Multi-image entity. Entity appearance is defined by element_image_list.

element_image_list object

Entity reference images. Allows defining the entity and its details using multiple images.

Must include at least 1 frontal reference image (defined by frontal_image) and 1–3 additional reference images from other angles or close-ups (must differ from the frontal image, defined by refer_images[].image_url).

"element_image_list": {
  "frontal_image": "image_url_0",
  "refer_images": [
    {"image_url": "image_url_1"},
    ...
  ]
}

Supports image Base64 encoding or image URL (must be publicly accessible)
Supported formats: .jpg / .jpeg / .png
File size must not exceed 10MB; image dimensions must be at least 300px; aspect ratio must be between 1:2.5 and 2.5:1

Note: Required when reference_type is image_refer

frontal_image string required

Frontal reference image URL or Base64

refer_images array required

Additional reference images from other angles or close-ups, must differ from the frontal image

image_url string required

Image URL or Base64

element_video_list object

Entity reference video. Allows defining the entity and its details using a video.

Audio videos are supported; if the video contains human voice, voice customization is triggered (customized, added to voice library, and bound to the entity)
Currently only supports customizing realistic, humanoid entities via video
Supported formats: MP4/MOV; duration between 3s and 8s; 1080P video with 16:9 or 9:16 aspect ratio
Only 1 video supported; file size must not exceed 200MB; video_url must not be empty

"element_video_list": {
  "refer_videos": [
    {"video_url": "video_url_1"}
  ]
}

Note: Required when reference_type is video_refer

refer_videos array required

Reference video list

video_url string required

Video URL or Base64

element_voice_id string

Entity voice. Binds an existing voice from the voice library. When empty, no voice is bound to this entity.

Note: Only video-based entities support voice binding.

tag_list array

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

"tag_list": [
  {"tag_id": "o_101"},
  {"tag_id": "o_102"}
]
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

Entity information JSON string containing the following fields:
element_id: Entity ID
element_name: Entity name
element_description: Entity description
reference_type: Entity reference method
element_image_list: Reference images (present for multi-image entities)
element_image_list.frontal_image: Frontal reference image
element_image_list.refer_images[].image_url: Additional reference images
element_video_list: Reference video (present for video-based entities)
element_video_list.refer_videos[].video_url: Reference video
element_voice_id: Bound voice ID
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)