Skip to main content
POST
Create Custom Element

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
element_name
string
required

Name of the custom element, up to 20 characters.

Maximum string length: 20
Example:

"my-character"

element_description
string
required

Description of the custom element, up to 100 characters.

Maximum string length: 100
Example:

"A protagonist character for my video series"

reference_type
enum<string>
required

Reference method. image_refer defines appearance from multiple images; video_refer defines a video-character element from one reference video.

Available options:
image_refer,
video_refer
Example:

"image_refer"

element_image_list
object

Required when reference_type is image_refer. Provide one frontal image and 1–3 additional images from different angles or close-ups. Images accept accessible URLs or raw Base64; JPG/JPEG/PNG, max 10 MB, min 300 px per side, aspect ratio 1:2.5 to 2.5:1.

element_video_list
object

Required when reference_type is video_refer and ignored for image references. Supports one MP4/MOV video, 3–8 seconds, 1080p, 16:9 or 9:16, max 200 MB. Video-character customization is supported by Kling video O3 and later models.

element_voice_id
string

Optional voice ID to bind to the element. For image-based elements, voice binding is supported only for human or humanoid character elements.

tag_list
object[]

Tag list. Available tag_id values:

  • o_101: 热梗
  • o_102: 人物 (Character)
  • o_103: 动物
  • o_104: 道具
  • o_105: 服饰
  • o_106: 场景 (Scene)
  • o_107: 特效
  • o_108: 其他

Response

Element creation task submitted

id
string

Task ID

Example:

"863121016086724692"

task_id
string

Task ID (same as id)

Example:

"863121016086724692"

object
string

Fixed value video

Example:

"video"

model
string

Fixed value kling-element

Example:

"kling-element"

status
string

Initial task status.

Example:

"queued"

progress
integer

Progress 0–100

Example:

0

created_at
integer

Unix timestamp

Example:

1773812605