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:
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
# 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"]
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements",
headers={
"Authorization": "Bearer sk-your-token",
"Content-Type": "application/json",
},
json={
# Chinese name / description work best for the upstream model
"model": "kling-element",
"name": "我的主角",
"description": "短发年轻男性",
"frontal_image": "https://example.com/front.jpg",
"refer_images": ["https://example.com/side.jpg"],
},
)
task = resp.json()
print(task["data"]["task_id"], task["data"]["status"])
const resp = await fetch(
'https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements',
{
method: 'POST',
headers: {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Chinese name / description work best for the upstream model
model: 'kling-element',
name: '我的主角',
description: '短发年轻男性',
frontal_image: 'https://example.com/front.jpg',
refer_images: ['https://example.com/side.jpg'],
}),
},
);
const task = await resp.json();
console.log(task.data.task_id, task.data.status);
Create a Voice
POST /kling-asset/v1/assets/voices
# 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"
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/kling-asset/v1/assets/voices",
headers={
"Authorization": "Bearer sk-your-token",
"Content-Type": "application/json",
},
json={
# Chinese name works fine; any clean 5s+ human voice sample works
"model": "kling-voice",
"name": "温柔女声",
"voice_url": "https://example.com/sample.wav",
},
)
task = resp.json()
print(task["data"]["task_id"], task["data"]["status"])
const resp = await fetch(
'https://api-model.shuntianchuang.cn/kling-asset/v1/assets/voices',
{
method: 'POST',
headers: {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Chinese name works fine; any clean 5s+ human voice sample works
model: 'kling-voice',
name: '温柔女声',
voice_url: 'https://example.com/sample.wav',
}),
},
);
const task = await resp.json();
console.log(task.data.task_id, task.data.status);
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):
# 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"
import time
import requests
BASE = "https://api-model.shuntianchuang.cn"
HEADERS = {"Authorization": "Bearer sk-your-token"}
task_id = "task_xxxxxxxx" # data.task_id from the create response
while True:
data = requests.get(
f"{BASE}/kling-asset/v1/assets/elements/{task_id}", headers=HEADERS
).json()["data"]
print(data["status"])
if data["status"] in ("SUCCESS", "FAILURE"):
break
time.sleep(5)
print(data.get("element_id") or data.get("fail_reason"))
const BASE = 'https://api-model.shuntianchuang.cn';
const HEADERS = { Authorization: 'Bearer sk-your-token' };
const taskId = 'task_xxxxxxxx'; // data.task_id from the create response
let data;
while (true) {
const resp = await fetch(`${BASE}/kling-asset/v1/assets/elements/${taskId}`, {
headers: HEADERS,
});
data = (await resp.json()).data;
console.log(data.status);
if (data.status === 'SUCCESS' || data.status === 'FAILURE') break;
await new Promise((resolve) => setTimeout(resolve, 5_000));
}
console.log(data.element_id || data.fail_reason);
Delete example (for voices replace elements with voices and the field with voice_id):
# 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"}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/delete",
headers={
"Authorization": "Bearer sk-your-token",
"Content-Type": "application/json",
},
json={"element_id": "324465195791137"},
)
print(resp.json()["data"])
const resp = await fetch(
'https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/delete',
{
method: 'POST',
headers: {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({ element_id: '324465195791137' }),
},
);
console.log((await resp.json()).data);
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:
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 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:
# 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 跟随参考视频的动作跳舞" }
]
}
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-your-token",
"Content-Type": "application/json",
},
json={
"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"},
# @elementId naming goes in the contents prompt item
{"type": "prompt", "text": "让 @324465195791137 跟随参考视频的动作跳舞"},
],
},
},
)
task = resp.json()
print(task["id"])
const resp = await fetch('https://api-model.shuntianchuang.cn/v1/videos', {
method: 'POST',
headers: {
Authorization: 'Bearer sk-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
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',
},
// @elementId naming goes in the contents prompt item
{ type: 'prompt', text: '让 @324465195791137 跟随参考视频的动作跳舞' },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
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.