Subject (New Version)

POST https://www.kkiai.com/kling/v1/general/advanced-custom-elements

Request Parameters

Authorization

Add the Authorization parameter to the Header. Its value is the Token concatenated after Bearer.

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

Header Parameters

Parameter Name	Type	Required	Description	Example
Content-Type	string	Optional		application/json
Authorization	string	Optional		Bearer {{YOUR_API_KEY}}

Body Parameters (application/json)

Parameter Name	Type	Required	Description
element_name	string	Required	Cannot exceed 20 characters
element_description	string	Required	Cannot exceed 100 characters
reference_type	string	Required	Enum values: video_refer, image_refer video_refer: Video character subject. In this case, the subject appearance will be defined by element_video_list image_refer: Multi-image subject. In this case, the subject appearance will be defined by element_image_list The available scope differs between subjects customized via video and subjects customized via images. See the capability map and parameter documentation for details.
element_image_list	object	Optional	Define the subject and its details through multiple images. This includes a frontal reference image and reference images from other angles or close-ups. At least 1 frontal reference image must be included (defined by the frontal_image parameter); 1-3 additional reference images must be included and should differ from the frontal image (defined by the image_url parameter). Carried as key:value pairs, as follows: "element_image_list": { "frontal_image": "image_url_0", "refer_images": [{ "image_url": "image_url_1" }, ...] } Supports Base64-encoded images or image URLs (ensure accessibility). Supported image formats: .jpg / .jpeg / .png. Image file size cannot exceed 10MB. Image dimensions must be at least 300px. Image aspect ratio must be between 1:2.5 and 2.5:1. This parameter is required when reference_type is image_refer.
└ frontal_image	string	Optional
└ refer_images	array[object]	Optional
element_video_list	object	Optional	Define the subject and its details through video. Supports uploading videos with audio. If the audio contains human voice, voice customization is triggered (customization + voice library entry + binding with subject). Currently only supports customizing realistic human-form images through video. This parameter is required when referencing video and invalid when referencing images. Carried as key:value pairs. Video format supports only MP4/MOV. Only supports videos with duration between 3s-8s, aspect ratio of 16:9 or 9:16, and 1080P resolution. At most 1 video can be uploaded, with size not exceeding 200MB. The video_url parameter value cannot be empty. "element_video_list": { "refer_videos": [{ "video_url": "video_url_1" }, ...] } Subjects customized via video are only supported for kling-video-o3 and later models.
└ refer_videos	array[object]	Optional
element_voice_id	string	Optional	Can bind an existing voice from the voice library. When this parameter is empty, the current subject will not be bound to a voice. Voice IDs can be obtained through voice-related APIs. Click here to view. Only subjects customized via video support voice binding.
tag_list	array[object]	Optional	A subject can be configured with multiple tags. Carried as key:value pairs. Tag IDs and names: o_101 Trending, o_102 Character, o_103 Animal, o_104 Prop, o_105 Clothing, o_106 Scene, o_107 Effect, o_108 Other
└ tag_id	string	Optional
callback_url	string	Optional	Callback notification URL for this task result. If configured, the server will actively notify when the task status changes.
external_task_id	string	Optional	Custom task ID. User-defined task ID. Passing this will not override the system-generated task ID, but supports task queries through this ID. Note: Must be unique per user.

Request Example

{
    "element_name": "bodyysh11112311213",
    "element_description": "test",
    "reference_type": "image_refer",
    "element_image_list": {
        "frontal_image": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png",
        "refer_images": [
            {
                "image_url": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png"
            }
        ]
    },
    // "element_video_list": {
    //     "refer_videos": [
    //         {
    //             "video_url": "xxx"
    //         }
    //     ]
    // },
    // "element_voice_id": string,
    // "tag_list": [
    //     {
    //         "tag_id": "xxx"
    //     }
    // ],
    // "callback_url": "xxx",
    // "external_task_id": ""
}

cURL Example

curl --location --request POST 'https://www.kkiai.com/kling/v1/general/advanced-custom-elements' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "element_name": "bodyysh11112311213",
    "element_description": "test",
    "reference_type": "image_refer",
    "element_image_list": {
        "frontal_image": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png",
        "refer_images": [
            {
                "image_url": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png"
            }
        ]
    },
    // "element_video_list": {
    //     "refer_videos": [
    //         {
    //             "video_url": "xxx"
    //         }
    //     ]
    // },
    // "element_voice_id": string,
    // "tag_list": [
    //     {
    //         "tag_id": "xxx"
    //     }
    // ],
    // "callback_url": "xxx",
    // "external_task_id": ""
}'

Response

🟢 200 Success

Response Example

{}