Create Subject

POST

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

Create a custom subject for use in later video generation and related features.

Authorizations

bearer

Type

HTTP (bearer)

Request Body

application/json

object

Must not exceed 20 characters.

Must not exceed 100 characters.

Allowed values: video_refer, image_refer

• video_refer: video character subject; appearance is defined by element_video_list
• image_refer: multi-image subject; appearance is defined by element_image_list
  Subjects created from video vs. images have different supported capabilities; see the capability map and parameter notes.

object

Define the subject and its details with multiple images.

Includes a frontal reference and other angle or close-up references: at least one frontal image via frontal_image; 1–3 additional images that differ from the frontal image via image_url.

Payload shape:

"element_image_list": {
"frontal_image": "image_url_0",
"refer_images": [{ "image_url": "image_url_1" }, ...]
}

Supports Base64-encoded images or image URLs (must be accessible).

Formats: .jpg / .jpeg / .png. Max file size 10MB; min dimensions 300px; aspect ratio between 1:2.5 and 2.5:1.

Required when reference_type is image_refer.

object

Define the subject and its details with video.

Audio-bearing videos may trigger voice customization when human speech is present (train, store in the voice library, and bind to the subject).

Currently only supports creating realistic human subjects from video.

Required when using video reference; ignored when using image reference.

Payload shape. Formats: MP4/MOV only. Duration 3–8s; aspect ratio 16:9 or 9:16; 1080p. At most one video; max 200MB. video_url must not be empty.

"element_video_list": {
"refer_videos": [{ "video_url": "video_url_1" }, ...]
}

Video-based subjects are only supported on kling-video-o3 and later models.

Bind an existing voice from the voice library.

If empty, no voice is bound to this subject.

Obtain IDs via voice-related APIs.

Only video-based subjects support voice binding.

object[]

A subject may have multiple tags.

Payload shape. Tag IDs and names: o_101 meme, o_102 person, o_103 animal, o_104 prop, o_105 costume, o_106 scene, o_107 effect, o_108 other

Callback URL for task status updates when configured.

Caller-defined task ID. Does not replace the system task ID but can be used for task lookup. Must be unique per user.