Create Subject

POST

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

Actual request URL: POST https://api.tokenhot.ai/v1/general/advanced-custom-elements

Create a reusable "subject (element)" for maintaining character/object consistency in video generation. Async interface: returns a task_id; poll with the "Query Subject" endpoint, then retrieve the subject ID from Output.InfoList[].ElementId once finished.

Supports two subject types:

image_refer (multi-image subject): 1 frontal image + 1~3 variation images.

video_refer (video character subject): 1 reference video.

Both types can be bound to a voice via element_voice_id.

⚠️ Actual validation notes (upstream enforcement differs from documentation):

element_description is actually required (omitting it returns ElementDescription is required).

In image_refer mode, refer_images actually requires at least 1 image (1~3; an empty array is rejected).

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Submission successful, returns task ID

Bodyapplication/json

Request Example

Shell

JavaScript

Java

Swift

cURL

Multi-image subject image_referVideo character subject video_refer

curl --location 'https://api.tokenhot.ai/v1/general/advanced-custom-elements' \
--header 'Authorization: Bearer <token>' \
--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

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

Modified at 2026-06-23 06:58:26

Subject-Controlled Video Generation (kling-v3-omni)

Query Subject