Elements & Voices (Kling Unified Format)

Elements (custom subject images) and voices (cloned voices) are created through the asset-management endpoints first; the resulting IDs are then referenced in metadata.contents of video generation (see Submit Task · Element & Voice References). Authentication is identical to the video endpoints: pass Authorization: Bearer your-token in the header.

Asset Models & Routes

Two namespaces map to the two model series; asset IDs are not interchangeable:

Assetkling series (kling-* models)kling-v series (kling-v-* models)
Elementkling-elementkling-v-element
Voicekling-voicekling-v-voice

Route prefixes: the kling series lives under /kling-asset/v1/assets/ (create / query / delete), the kling-v series under /kling-v-asset/v1/assets/ (create / query, no delete). Examples below use the kling-series routes — for the kling-v series swap the prefix and pseudo-model (differences noted in the tables).

Create an Element

POST /kling-asset/v1/assets/elements

FieldRequiredDescription
modelYeskling-element (kling-v-element for the kling-v series)
nameYesElement name, ≤ 20 characters
frontal_imageYesFrontal image URL
refer_imagesOptional for kling / required for kling-v1–3 supplementary reference image URLs (side views, other angles); kling defaults to reusing the frontal image, kling-v returns 400 when missing or out of range
descriptionNoElement description, ≤ 100 characters; defaults to name
cURL
Python
Node.js
# Create an element; Chinese description works best for the upstream model
curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-element",
    "name": "我的主角",
    "description": "短发年轻男性",
    "frontal_image": "https://example.com/front.jpg",
    "refer_images": ["https://example.com/side.jpg"]
  }'

Create a Voice

POST /kling-asset/v1/assets/voices

FieldRequiredDescription
modelYeskling-voice (kling-v-voice for the kling-v series)
nameYesVoice name, ≤ 20 characters
voice_urlYesReference audio URL: a single clean human voice, about 5 s or longer (kling-v series accepts .mp3 / .wav / .mp4 / .mov, 5–30 s)
cURL
Python
Node.js
# Create a cloned voice from a reference audio clip
curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/voices \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-voice",
    "name": "温柔女声",
    "voice_url": "https://example.com/sample.wav"
  }'

Query and Delete

Query: GET /kling-asset/v1/assets/elements/{task_id} (for voices, replace elements with voices).

Delete (kling series only): POST /kling-asset/v1/assets/elements/delete with body {"element_id": "…"}; for voices use /voices/delete + {"voice_id": "…"}. After deletion, querying returns deleted: true; deleted IDs can no longer be referenced by video generation.

Polling example (element; for voices replace elements with voices in the path):

cURL
Python
Node.js
# Query element status; replace elements with voices for voice assets
curl https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/task_xxxxxxxx \
  -H "Authorization: Bearer sk-your-token"

Delete example (for voices replace elements with voices and the field with voice_id):

cURL
Python
Node.js
# Delete an element; voices use /voices/delete + {"voice_id": "..."}
curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/delete \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{"element_id": "324465195791137"}'

Response Structure

Responses use the unified envelope {code, message, data}; data has five fixed fields and the same four-value status vocabulary as the video query endpoint:

FieldDescription
data.task_idAsset task id
data.statusFour values: QUEUED → IN_PROGRESS → SUCCESS / FAILURE
data.element_idElement ID, non-empty only when an element task reaches SUCCESS
data.voice_idVoice ID, non-empty only when a voice task reaches SUCCESS
data.fail_reasonNon-empty only on FAILURE

deleted is appended as true only on the terminal state of a delete task. element_id / voice_id are the IDs referenced in video generation contents; on failure data.fail_reason carries the reason.

// Queued / creating
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxx",
    "status": "QUEUED",
    "element_id": "",
    "voice_id": "",
    "fail_reason": ""
  }
}
// Element created
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxx",
    "status": "SUCCESS",
    "element_id": "324465195791137",
    "voice_id": "",
    "fail_reason": ""
  }
}
// Delete terminal state (kling series only, extra deleted: true)
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxxxxxxx",
    "status": "SUCCESS",
    "element_id": "324465195791137",
    "voice_id": "",
    "fail_reason": "",
    "deleted": true
  }
}

Referencing in Video Generation

Referencing takes two steps, both required: step 1 declares the material in the video submit's metadata.contents (bringing the ID into the task), step 2 names the material in the prompt (telling the model which one to use). For general-scenario examples see Submit Task · Element & Voice References.

Step 1 · declare in contents:

  • Element: {"type": "element", "id": "<elementId>"}; optionally add "name" to help the upstream recognize the subject name (does not affect matching);
  • Voice: {"type": "voice", "id": "<voiceId>"};
  • Motion-control tasks additionally require: {"type": "element", "id": "<elementId>", "element_id": "<elementId>"} — id and element_id must both be present with the same value; missing either returns 400;
  • The ID is the element_id / voice_id from the asset creation task's terminal state (see Elements & Voices, plain numeric strings like 325057409061256) — not the asset name, nor the asset task's task_id.

Step 2 · name it in the prompt: two notations exist, chosen by task type — they are not interchangeable.

Notation A: <<<element_N>>> / <<<voice_N>>> placeholdersNotation B: @<elementId>
Applies toRegular tasks: omni t2v direct reference / i2v with a first frame elsewhereMotion-control tasks (kling-motion-3.0 series) referencing an element
Prompt formPlaceholders embedded in natural language: let <<<element_1>>> face the camera, say…Write @ plus the element ID: let @325057409061256 follow the dance
contents itemelement carries id (optional name); voice carries idelement must carry both id and element_id (same value)
Nameable materialsBoth elements and voices, multiple allowedElements only (motion tasks do not support voice references)

Notation A numbering rules:

  • N counts same-type materials in contents order starting from 1 — elements and voices are counted independently, regardless of ID values; with 2 elements + 1 voice declared, name them <<<element_1>>>, <<<element_2>>>, <<<voice_1>>>;
  • The same placeholder may appear multiple times in the prompt; naming every material is not required, but naming is how the model explicitly follows a material — submitting with only id also works, naming is recommended;
  • Placeholders are matched by the upstream per sequence number; the site only passes the prompt text through without string replacement — write them exactly as specified: three angle brackets with the number tightly attached (<<<element_1>>>); malformed forms like <<element_1>> or <<< element_1 >>> do not error but may not be recognized as material references.

Notation B boundaries:

  • Used only when a motion task references an element; @ is followed by the value of the contents item's id key. Put the prompt in the contents {"type": "prompt", "text": "…"} item with the @ naming inside that text (the top-level prompt also works; when both exist the top level wins);
  • Do not use @ on regular tasks and do not use <<<>>> on motion tasks — the two notations map to two distinct upstream material-injection mechanisms; cross-scenario behavior is undefined.

Motion-control tasks referencing an element (kling-motion-3.0 series, ≤ 1) — the element item carries both id and element_id (same value), named with notation B (@<elementId>) inside the contents prompt item:

cURL
Python
Node.js
# Motion-control element reference: element item carries id + element_id (same value);
# name it with @elementId inside the contents prompt item
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-motion-3.0",
    "metadata": {
      "character_orientation": "video",
      "audio": "original",
      "contents": [
        { "type": "image", "url": "https://example.com/character.webp" },
        { "type": "video", "url": "https://example.com/dance.mp4" },
        { "type": "element", "id": "324465195791137", "element_id": "324465195791137" },
        { "type": "prompt", "text": "让 @324465195791137 跟随参考视频的动作跳舞" }
      ]
    }
  }'

Reference constraints (violations return 400 at submit):

  • Quantity: elements ≤ 3 on regular tasks; motion-control only kling-motion-3.0 series and ≤ 1 (kling-motion-2.6 does not support elements); voices ≤ 2;
  • Voices require a sounding audio tier: when contents contains a voice, metadata.audio must be explicitly native / original (silent default → 400). Models without audio support (kling-2.5-turbo / kling-3.0-turbo series) and the off-only kling-v-o1 therefore cannot use voices; motion tasks do not support voice references;
  • kling-2.6 tier change: voice tasks require audio=native; they are forced to 1080p and billed at 1080p;
  • t2v material restriction: t2v on non-omni models (no image, no first/last frames) cannot carry contents — add an image (i2v, see above) or use an omni model for direct t2v reference;
  • Namespace alignment: kling-* models only accept IDs created under /kling-asset; kling-v-* models only under /kling-v-asset. Cross-series references are invalid;
  • Mixing allowed: elements and voices can appear in the same task, or be referenced separately;
  • Never reference deleted assets: kling-series assets can be deleted (see Elements & Voices); deleted elements / voices can no longer be referenced — tasks referencing a deleted ID fail.

Reference constraints (violations return 400 at submit):

  • Quantity: elements ≤ 3 on regular tasks; motion-control only kling-motion-3.0 series and ≤ 1 (kling-motion-2.6 does not support elements); voices ≤ 2;
  • Voices require a sounding audio tier: when contents contains a voice, metadata.audio must be explicitly native / original (silent default → 400). Models without audio support (kling-2.5-turbo / kling-3.0-turbo series) and the off-only kling-v-o1 therefore cannot use voices; motion tasks do not support voice references;
  • kling-2.6 tier change: voice tasks require audio=native; they are forced to 1080p and billed at 1080p;
  • t2v material restriction: t2v on non-omni models (no image, no first/last frames) cannot carry contents — add an image (i2v) or use an omni model for direct t2v reference;
  • Namespace alignment: kling-* models only accept IDs created under /kling-asset; kling-v-* models only under /kling-v-asset. Cross-series references are invalid;
  • Mixing allowed: elements and voices can appear in the same task, or be referenced separately;
  • Never reference deleted assets: kling-series assets can be deleted (see Query and Delete); deleted elements / voices can no longer be referenced — tasks referencing a deleted ID fail.