Kling Custom Elements

kling-custom-elements

kling-custom-elements Kling Custom Elements kirin_custom_elements kling

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

Эндпоинты

POST /v1/queue/kling-custom-elements # Создать задачу

GET /v1/queue/kling-custom-elements/requests/{request_id}/status # Проверить статус

GET /v1/queue/kling-custom-elements/requests/{request_id}/response # Получить результат

PUT /v1/queue/kling-custom-elements/requests/{request_id}/cancel # Отменить задачу

Совет

Добавляйте заголовок аутентификации в каждый запрос: Authorization: Bearer YOUR_API_KEY.

Параметры запроса

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": "主体名称",
  "element_description": "AI生成人物主体",
  "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.

Параметры ответа

{
  "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
}

Поле	Тип	Описание
request_id	string	Идентификатор задачи для последующей проверки статуса, получения результата и отмены.
response_url	string	URL для получения итогового результата.
status_url	string	URL для проверки статуса задачи.
cancel_url	string	URL для отмены задачи.
queue_position	int	Текущая позиция в очереди.

Следующие операции

Проверить статус

Получить результат

Отменить задачу

Обработка ошибок