⌘K

Kirin Custom Elements

kirin_custom_elements

Custom Elements 主体配置接口, 用于创建可复用主体并配置参考图与标签.

认证

authorization string 必填

所有 API 均使用 Bearer Token 鉴权

获取 API Key：

访问 API Key 管理页面 获取 API Key

用法：

将以下 Header 添加到请求中：

Authorization: Bearer YOUR_API_KEY

参数

model string 必填

请求使用的模型 ID

值: kirin_custom_elements

element_name string 必填

主体名称

注：不能超过 20 个字符

element_description string 必填

主体描述

注：不能超过 100 个字符

reference_type string 必填

主体参考方式

可选值:
video_refer：视频角色主体, 将参考 element_video_list 定义主体外表
image_refer：多图主体, 将参考 element_image_list 定义主体外表

element_image_list object

主体参考图, 可通过多张图片设定主体及其细节

包括正面参考图（由 frontal_image 定义）和 1～3 张其他角度或特写参考图（需与正面参考图有差异, 由 refer_images[].image_url 定义）

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

支持传入图片 Base64 编码或图片 URL（确保可访问）
图片格式支持 .jpg / .jpeg / .png
图片文件大小不能超过 10MB, 图片宽高尺寸不小于 300px, 图片宽高比要在 1:2.5 ～ 2.5:1 之间

注：reference_type 为 image_refer 时必填

frontal_image string 必填

正面参考图的图片 URL 或 Base64

refer_images array 必填

其他角度或特写参考图列表, 需与正面参考图有差异

image_url string 必填

图片 URL 或 Base64

element_video_list object

主体参考视频, 可通过视频设定主体及其细节

可上传有声视频, 有声视频包含人声则触发音色定制（定制 + 入音色库 + 与主体绑定）
暂时仅支持通过视频定制写实风格、人形形象
视频格式仅支持 MP4/MOV, 时长介于 3s～8s 之间, 宽高比需为 16:9 或 9:16 的 1080P 视频
至多仅支持上传 1 段视频, 视频大小不超过 200MB, video_url 参数值不得为空

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

注：reference_type 为 video_refer 时必填

refer_videos array 必填

参考视频列表

video_url string 必填

视频 URL 或 Base64

element_voice_id string

主体音色, 可绑定音色库中已有音色. 为空时当前主体不绑定音色

注：仅视频定制的主体支持绑定音色

tag_list array

为主体配置标签, 一个主体可以配置多个标签

"tag_list": [
  {"tag_id": "o_101"},
  {"tag_id": "o_102"}
]
tag_id名称
o_101热梗
o_102人物
o_103动物
o_104道具
o_105服饰
o_106场景
o_107特效
o_108其他

tag_id string 必填

标签 ID

可选值: o_101、o_102、o_103、o_104、o_105、o_106、o_107、o_108

callback_url string

回调 URL

external_task_id string

自定义任务 ID, 传入不会覆盖系统生成的任务 ID, 但支持通过该 ID 进行任务查询

注：单用户下需要保证唯一性

轮询

由于结果生成需要时间，您需要在创建任务后轮询任务状态

初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取

轮询请求与响应示例见右侧

响应格式

output array

生成结果, 仅在状态为 completed 时出现

content array

生成内容列表

text string

主体信息 JSON 字符串, 包含以下参数：
element_id：主体 ID
element_name：主体名称
element_description：主体描述
reference_type：主体参考方式
element_image_list：主体参考图（多图主体时存在）
element_image_list.frontal_image：正面参考图
element_image_list.refer_images[].image_url：其他参考图
element_video_list：主体参考视频（视频角色主体时存在）
element_video_list.refer_videos[].video_url：参考视频
element_voice_id：绑定的音色 ID
tag_list：标签列表
tag_list[].id：标签 ID
tag_list[].name：标签名称
tag_list[].description：标签描述
owned_by：主体归属用户 ID
final_unit_deduction：最终扣费额度

type string

资源类型, 此接口返回 text

url string

URL（此接口为空）