创建主体

POST

https://api.tokenhot.ai/v1/general/advanced-custom-elements

实际请求地址: POST https://api.tokenhot.ai/v1/general/advanced-custom-elements

创建一个可复用的「主体(element)」用于视频生成时保持角色/物体一致性。异步接口:返回 task_id,需用「查询主体」接口轮询,成功后从 Output.InfoList[].ElementId 获取主体 ID。

支持两种主体类型:

image_refer(多图主体):1 张正面图 + 1~3 张差异图。

video_refer(视频角色主体):1 段参考视频。

两种类型均可绑定音色 element_voice_id。

⚠️ 实测注意(上游实际校验,文档标注与实际有出入):

element_description 实际必填(缺失会返回 ElementDescription is required)。

image_refer 模式下 refer_images 实际至少 1 张(1~3 张,空数组会被拒)。

Request

Authorization

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

提交成功,返回任务 ID

Bodyapplication/json

🟠400

🟠401

🔴503

Request Example

Shell

JavaScript

Java

Swift

cURL

多图主体 image_refer视频角色主体 video_refer

curl --location 'https://api.tokenhot.ai/v1/general/advanced-custom-elements' \
--header 'Content-Type: application/json' \
--data '{
    "element_name": "hero",
    "element_description": "a young hero character",
    "reference_type": "image_refer",
    "element_image_list": {
        "frontal_image": "https://example.com/face.jpg",
        "refer_images": [
            {
                "image_url": "https://example.com/side.jpg"
            },
            {
                "image_url": "https://example.com/back.jpg"
            }
        ]
    },
    "session_id": "unique_session_002"
}'

Response Example

200 - 成功示例

{
    "Response": {
        "TaskId": "1500062068-CreateAigcAdvancedCustomElement-7671dd6d88b91859db70653ac3b06400t",
        "RequestId": "a3193d46-89d5-47f6-a9af-20b71e6526b7"
    }
}

主体控制生成视频 (kling-v3-omni)

查询主体