Kling Custom Elements

kling-custom-elements

Custom Elements entity configuration API for creating reusable entities with reference images and tags.

Endpoints

POST /v1/queue/kling-custom-elements # Create task

GET /v1/queue/kling-custom-elements/requests/{request_id}/status # Check status

GET /v1/queue/kling-custom-elements/requests/{request_id}/response # Get result

PUT /v1/queue/kling-custom-elements/requests/{request_id}/cancel # Cancel task

Request parameters

curl --request 'POST' 'https://odirouter.ai/model/v1/queue/kling-custom-elements' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --location \
  --data-raw '{
  "element_name": "custom_character",
  "element_description": "AI generated character subject",
  "element_frontal_image": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-1.png",
  "element_refer_list": [
    {
      "image_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-2.png"
    },
    {
      "image_url": "https://v1-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-4.png"
    }
  ],
  "tag_list": [
    {
      "tag_id": "o_102"
    }
  ]
}'

element_name string required

Entity name

Must not exceed 20 characters

element_description string required

Entity description

Must not exceed 100 characters

reference_type string required

Entity reference method

Options:

video_refer: Video-based entity. Entity appearance is defined by element_video_list.

image_refer: Multi-image entity. Entity appearance is defined by element_image_list.

element_image_list object

Entity reference images. Allows defining the entity and its details using multiple images.

Must include at least 1 frontal reference image (defined by frontal_image) and 1–3 additional reference images from other angles or close-ups (must differ from the frontal image, defined by refer_images[].image_url).

"element_image_list": {

"frontal_image": "image_url_0",

"refer_images": [

{"image_url": "image_url_1"},

...

]

}

Supports image Base64 encoding or image URL (must be publicly accessible)

Supported formats: .jpg / .jpeg / .png

File size must not exceed 10MB; image dimensions must be at least 300px; aspect ratio must be between 1:2.5 and 2.5:1

Note: Required when reference_type is image_refer

frontal_image string required

Frontal reference image URL or Base64

refer_images array required

Additional reference images from other angles or close-ups, must differ from the frontal image

image_url string required

Image URL or Base64

element_video_list object

Entity reference video. Allows defining the entity and its details using a video.

Audio videos are supported; if the video contains human voice, voice customization is triggered (customized, added to voice library, and bound to the entity)

Currently only supports customizing realistic, humanoid entities via video

Supported formats: MP4/MOV; duration between 3s and 8s; 1080P video with 16:9 or 9:16 aspect ratio

Only 1 video supported; file size must not exceed 200MB; video_url must not be empty

"element_video_list": {

"refer_videos": [

{"video_url": "video_url_1"}

]

}

Note: Required when reference_type is video_refer

refer_videos array required

Reference video list

video_url string required

Video URL or Base64

element_voice_id string

Entity voice. Binds an existing voice from the voice library. When empty, no voice is bound to this entity.

Note: Only video-based entities support voice binding.

tag_list array

Configure tags for the entity. One entity can have multiple tags.

"tag_list": [

{"tag_id": "o_101"},

{"tag_id": "o_102"}

]

tag_id	Name
o_101	Trending Meme
o_102	Character
o_103	Animal
o_104	Prop
o_105	Clothing
o_106	Scene
o_107	Effect
o_108	Other

tag_id string required

Tag ID

Options: o_101, o_102, o_103, o_104, o_105, o_106, o_107, o_108

callback_url string

Callback URL

external_task_id string

Custom task ID. Does not override the system-generated task ID but can be used to query the task.

Note: Must be unique per user.

Response parameters

{
  "request_id": "task_01hxyz...",
  "response_url": "https://odirouter.ai/model/v1/queue/kling-custom-elements/requests/task_01hxyz.../response",
  "status_url": "https://odirouter.ai/model/v1/queue/kling-custom-elements/requests/task_01hxyz.../status",
  "cancel_url": "https://odirouter.ai/model/v1/queue/kling-custom-elements/requests/task_01hxyz.../cancel",
  "queue_position": 0
}

Field	Type	Description
`request_id`	string	Task ID used for all follow-up operations.
`response_url`	string	URL to fetch the final result.
`status_url`	string	URL to query task status.
`cancel_url`	string	URL to cancel the task.
`queue_position`	int	Current queue position.

Follow-up operations

Check status

Get result

Cancel task

Error handling