元素与音色(可灵统一格式)
元素(自定义主体形象)与音色(克隆音色)先通过资产管理接口创建、拿到 ID,再在视频生成的 metadata.contents 里引用(见提交任务 · 引用元素与音色)。鉴权与视频接口相同:请求头携带 Authorization: Bearer 你的令牌。
资产模型与路由
两套命名空间按模型系列对应,资产 ID 不互通:
路由前缀:kling 系列为 /kling-asset/v1/assets/(创建 / 查询 / 删除),kling-v 系列为 /kling-v-asset/v1/assets/(创建 / 查询,无删除)。以下均以 kling 系列路由书写,kling-v 系列替换前缀与伪模型即可(差异见表格备注)。
创建元素
POST /kling-asset/v1/assets/elements
curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements \
-H "Authorization: Bearer sk-你的令牌" \
-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-你的令牌",
"Content-Type": "application/json",
},
json={
"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-你的令牌',
'Content-Type': 'application/json',
},
body: JSON.stringify({
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);
创建音色
POST /kling-asset/v1/assets/voices
curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/voices \
-H "Authorization: Bearer sk-你的令牌" \
-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-你的令牌",
"Content-Type": "application/json",
},
json={
"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-你的令牌',
'Content-Type': 'application/json',
},
body: JSON.stringify({
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);
查询与删除
查询:GET /kling-asset/v1/assets/elements/{task_id}(音色把 elements 换成 voices)。
删除(仅 kling 系列):POST /kling-asset/v1/assets/elements/delete,body 为 {"element_id": "…"};音色为 /voices/delete + {"voice_id": "…"}。删除后查询返回 deleted: true;删除后的 ID 不可再被视频生成引用。
查询轮询示例(元素;音色把路径中 elements 换成 voices):
curl https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/task_xxxxxxxx \
-H "Authorization: Bearer sk-你的令牌"
import time
import requests
BASE = "https://api-model.shuntianchuang.cn"
HEADERS = {"Authorization": "Bearer sk-你的令牌"}
task_id = "task_xxxxxxxx" # 创建响应中的 data.task_id
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-你的令牌' };
const taskId = 'task_xxxxxxxx'; // 创建响应中的 data.task_id
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);
删除示例(音色把路径中 elements 换成 voices、字段换成 voice_id):
curl -X POST https://api-model.shuntianchuang.cn/kling-asset/v1/assets/elements/delete \
-H "Authorization: Bearer sk-你的令牌" \
-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-你的令牌",
"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-你的令牌',
'Content-Type': 'application/json',
},
body: JSON.stringify({ element_id: '324465195791137' }),
},
);
console.log((await resp.json()).data);
响应结构
出参统一包络 {code, message, data},data 固定五字段,状态词表与视频查询路由一致(四值大写):
deleted 仅删除任务终态附加 true。element_id / voice_id 即视频生成 contents 里引用的 ID;失败时 data.fail_reason 给出原因。
// 创建中 / 排队
{
"code": "success",
"message": "",
"data": {
"task_id": "task_xxxxxxxx",
"status": "QUEUED",
"element_id": "",
"voice_id": "",
"fail_reason": ""
}
}
// 元素创建成功
{
"code": "success",
"message": "",
"data": {
"task_id": "task_xxxxxxxx",
"status": "SUCCESS",
"element_id": "324465195791137",
"voice_id": "",
"fail_reason": ""
}
}
// 删除终态(仅 kling 系列,附加 deleted: true)
{
"code": "success",
"message": "",
"data": {
"task_id": "task_xxxxxxxx",
"status": "SUCCESS",
"element_id": "324465195791137",
"voice_id": "",
"fail_reason": "",
"deleted": true
}
}
在视频生成中引用
引用分两步,缺一不可:第 1 步在视频提交的 metadata.contents 里声明素材(把 ID 带进任务),第 2 步在提示词里点名素材(告诉模型用哪个)。通用场景的完整示例见提交任务 · 引用元素与音色。
第 1 步 · contents 声明:
- 元素:
{"type": "element", "id": "<元素ID>"},可另带 "name" 便于上游识别主体名称(不影响匹配);
- 音色:
{"type": "voice", "id": "<音色ID>"};
- 动作控制任务的元素项额外要求:
{"type": "element", "id": "<元素ID>", "element_id": "<元素ID>"}——id 与 element_id 必须同时携带且同值,缺任一键返回 400;
- ID 填元素与音色创建任务终态返回的
element_id / voice_id(纯数字串,如 325057409061256)——不是资产名称,也不是资产任务的 task_id。
第 2 步 · 提示词点名:两种写法按任务类型二选一,互不通用。
写法 A 的编号规则:
- N 按
contents 中同类素材的出现顺序从 1 编号,元素、音色各自独立计数,与 ID 数值无关——声明 2 个元素 + 1 个音色时,分别用 <<<element_1>>>、<<<element_2>>>、<<<voice_1>>> 点名;
- 同一占位符可在提示词中出现多次;不必每个素材都被点名,但点名是模型明确遵循该素材的方式,只传
id 也能提交,建议始终点名;
- 占位符由上游按序号匹配,站点只透传提示词原文、不做字符串替换——务必原样书写:三个尖括号包裹、紧贴编号(
<<<element_1>>>);写成 <<element_1>>、<<< element_1 >>> 等非规范形态不会报错,但可能不被识别为素材引用。
写法 B 的使用边界:
@ 后写 contents 项 id 键的值(即元素 ID);提示词建议走 contents 的 {"type": "prompt", "text": "…"} 项、@ 点名写在该 text 中(写在顶层 prompt 也可,两处同时存在时顶层优先);
- 普通任务不要用
@ 写法、动作控制任务不要用 <<<>>> 写法——两种写法对应上游两套素材注入机制,互不通用,跨场景书写行为未定义。
动作控制任务引用元素(kling-motion-3.0 系,≤ 1 个)——元素项同时带 id 与 element_id(同值),用写法 B 的 @<元素ID> 在 contents 的提示词项中点名:
# 动作控制引用元素:element 项带 id + element_id(同值),@ 点名写在 contents 的 prompt 项里
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-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-你的令牌",
"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"},
# @<元素ID> 点名写在 contents 的 prompt 项中
{"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-你的令牌',
'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',
},
// @<元素ID> 点名写在 contents 的 prompt 项中
{ type: 'prompt', text: '让 @324465195791137 跟随参考视频的动作跳舞' },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
引用约束清单(违反即提交 400):
- 数量:元素普通任务 ≤ 3 个;动作控制任务仅
kling-motion-3.0 系且 ≤ 1 个(kling-motion-2.6 系不支持元素);音色 ≤ 2 个;
- 音色必须配发声档:
contents 含 voice 时必须显式 metadata.audio 为 native / original(缺省 off → 400)。因此不支持 audio 的模型(kling-2.5-turbo / kling-3.0-turbo 系)与仅支持 off 档的 kling-v-o1 实际不可用音色;动作控制任务不支持音色引用;
- kling-2.6 系改档:指定音色的任务须
audio=native,自动按 1080p 生成并按 1080p 计费;
- 文生带素材限制:非全能模型的文生任务(无
image、无首尾帧)不能携带 contents——配 image 走图生(见上),或改用全能系文生直引;
- 命名空间对齐:
kling-* 模型只能引用 /kling-asset 创建的 ID,kling-v-* 模型只能引用 /kling-v-asset 创建的 ID,跨系引用无效;
- 可混用:元素与音色可同单混用,也可各自单独引用;
- 勿引用已删除的资产:kling 系列资产可删除(见元素与音色),删除后的元素 / 音色不可再引用,引用已删 ID 的任务会失败。
引用约束清单(违反即提交 400):
- 数量:元素普通任务 ≤ 3 个;动作控制任务仅
kling-motion-3.0 系且 ≤ 1 个(kling-motion-2.6 系不支持元素);音色 ≤ 2 个;
- 音色必须配发声档:
contents 含 voice 时必须显式 metadata.audio 为 native / original(缺省 off → 400)。因此不支持 audio 的模型(kling-2.5-turbo / kling-3.0-turbo 系)与仅支持 off 档的 kling-v-o1 实际不可用音色;动作控制任务不支持音色引用;
- kling-2.6 系改档:指定音色的任务须
audio=native,自动按 1080p 生成并按 1080p 计费;
- 文生带素材限制:非全能模型的文生任务(无
image、无首尾帧)不能携带 contents——配 image 走图生,或改用全能系文生直引;
- 命名空间对齐:
kling-* 模型只能引用 /kling-asset 创建的 ID,kling-v-* 模型只能引用 /kling-v-asset 创建的 ID,跨系引用无效;
- 可混用:元素与音色可同单混用,也可各自单独引用;
- 勿引用已删除的资产:kling 系列资产可删除(见查询与删除),删除后的元素 / 音色不可再引用,引用已删 ID 的任务会失败。