Developer docs
Docs Kling /kling/v1/general/advanced-custom-elements
API reference

Main body (new version)

POST/kling/v1/general/advanced-custom-elements

Body Parametersapplication/json

callback_url string

Task result callback URL; if set, server notifies on status changes

element_description* string

max 100 characters

element_image_list object

Define subject via multiple images: at least one frontal_image plus 1–3 differing refer_images (image_url). As key:value element_image_list. Base64 or URL; .jpg/.jpeg/.png; max 10MB; min 300px; aspect 1:2.5–2.5:1. Required when reference_type=image_refer

properties
frontal_image string

Frontal reference image

refer_images array

List of reference images

element_name* string

max 20 characters

element_video_list object

Define subject via video. Video with speech triggers voice customization. Realistic humans only for now. Required for video reference; ignored for image reference. MP4/MOV; 3–8s; 16:9 or 9:16 1080P; one clip ≤200MB; video_url required. Video-customized subjects only on kling-video-o3+

properties
refer_videos array

List of reference videos

element_voice_id string

can bind an existing voice from the library when this parameter is empty, this subject is not bound to a voice get IDs via voice APIs only video-customized subjects support voice binding

external_task_id string

Custom task ID. Does not override the system task ID, but can be used for queries. Must be unique per user

reference_type* string

enum: video_refer、 image_refer video_refer: video subject; appearance from element_video_list image_refer: multi-image subject; appearance from element_image_list Video- vs image-customized subjects differ in availability; see capability map / params.

tag_list array

A subject can have multiple tags as key:value. Tag IDs/names: o_101 meme, o_102 person, o_103 animal, o_104 prop, o_105 clothing, o_106 scene, o_107 VFX, o_108 other

items
object object

Responses

200 application/json
response-200 object
400 Bad request or validation failed application/json
response-400 object
properties
error* object
401 Missing or invalid API Key application/json
response-401 object
Request Body Example
1{
2"element_description": "测试",
3"element_image_list": {
4"frontal_image": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png",
5"refer_images": [
6{
7"image_url": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png"
8}
9]
10},
11"element_name": "主体ysh11112311213",
12"reference_type": "image_refer"
13}
Code Sample cURL
1curl -X POST "https://api.digislash.com/kling/v1/general/advanced-custom-elements" \
2-H "Authorization: Bearer <API Key>" \
3-H "Content-Type: application/json" \
4-d '{
5"element_description": "测试",
6"element_image_list": {
7"frontal_image": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png",
8"refer_images": [
9{
10"image_url": "https://imageproxy.zhongzhuan.chat/api/proxy/image/bb9bd34363da4fa486c9e645a6b1349e.png"
11}
12]
13},
14"element_name": "主体ysh11112311213",
15"reference_type": "image_refer"
16}'
Response
1▼{
2"code": 0,
3▼"data": {
4"task_id": "task_example_001"
5},
6"message": "success"
7}