#元素与音色(Element / Voice)
v3 系图生视频可引用元素(自定义主体),v2.6 / omni 系可引用音色(自定义配音)。元素与音色先通过两个管理模型创建(异步任务、免费),再在生成请求的 metadata.contents 里引用。
#创建并查询
第一步:创建并查询——用 chat 格式调用管理模型,业务参数全部放在 metadata(messages 内容不参与业务),响应的 content 是上游原始 JSON 字符串:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 管理模型名:kling-voice-manage(音色)或 kling-element-manage(元素) |
messages | array | 是 | chat 消息数组,内容任意,不参与业务,传固定值即可 |
metadata.op | string | 是 | 操作类型:create(创建)/ query(查询)/ delete(删除) |
metadata.voice_name | string | 创建音色必填 | 音色名称(≤20 字) |
metadata.voice_url | string | 二选一 | 参考音频公网直链,时长 ≥ 5 秒 |
metadata.video_id | string | 二选一 | 含音频的已生成视频 ID(与 voice_url 二选一) |
metadata.element_name | string | 创建元素必填 | 元素名称(≤20 字),@元素名 在 prompt 中引用 |
metadata.element_description | string | 创建元素必填 | 元素描述(≤100 字) |
metadata.frontal_image | string | 创建元素条件必填 | 元素正面照 URL(jpg/jpeg/png,上游会转存) |
metadata.refer_images | string[] | 否 | 参考图 URL 数组,实测 1~3 张;缺省自动补为 [frontal_image] |
metadata.model | string | 否 | 元素适用的模型,默认 kling-video-v3 |
metadata.reference_type | string | 否 | 参考类型,默认 image_refer |
metadata.tag_list | string[] | 否 | 标签列表 |
metadata.external_task_id | string | 否 | 自定义任务 ID(创建时传入,查询可回显) |
metadata.task_id | string | 查询必填 | 创建返回的任务 ID |
metadata.voice_id / metadata.element_id | string | 删除必填 | 要删除的音色/元素 ID |
管理操作免费(上游实测 quota 恒 "0")。
# 创建音色:voice_name 必填;voice_url(参考音频公网链接,时长 ≥ 5 秒)
# 或 video_id(含音频的已生成视频)二选一
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-voice-manage",
"messages": [{"role": "user", "content": "create"}],
"metadata": {
"op": "create",
"voice_name": "小美",
"voice_url": "https://cos.example.com/reference.wav"
}
}'
# 响应 content 里的 data.task_id 用于查询;创建免费# 创建元素:element_name(≤20 字)、element_description(≤100 字)、frontal_image(正面照 URL)必填
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-element-manage",
"messages": [{"role": "user", "content": "create"}],
"metadata": {
"op": "create",
"element_name": "小美",
"element_description": "一位年轻女性的正面肖像",
"frontal_image": "https://cos.example.com/portrait.jpg"
}
}'
# 响应 content 里的 data.task_id 用于查询;创建免费# 轮询(音色/元素通用):op 换成 query(传 task_id),建议 2~3 秒一次
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-voice-manage",
"messages": [{"role": "user", "content": "query"}],
"metadata": { "op": "query", "task_id": "929463831049801748" }
}'
# task_status = succeed 后,voice_id 在 content 的 data.task_result.voices[0].voice_id
# element_id 在 data.task_result.elements[0].element_id# 删除(同步返回):op 换成 delete(传 voice_id / element_id)
curl -X POST https://api-model.shuntianchuang.cn/v1/chat/completions \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-voice-manage",
"messages": [{"role": "user", "content": "delete"}],
"metadata": { "op": "delete", "voice_id": "929463831049801748" }
}'import json, time, requests
BASE = "https://api-model.shuntianchuang.cn"
HEADERS = {"Authorization": "Bearer sk-你的令牌", "Content-Type": "application/json"}
def manage(model, meta):
r = requests.post(f"{BASE}/v1/chat/completions", headers=HEADERS, timeout=60,
json={"model": model,
"messages": [{"role": "user", "content": "manage"}],
"metadata": meta})
r.raise_for_status()
return json.loads(r.json()["choices"][0]["message"]["content"])
# 创建音色
task = manage("kling-voice-manage",
{"op": "create", "voice_name": "小美",
"voice_url": "https://cos.example.com/reference.wav"})
task_id = task["data"]["task_id"]
# 轮询直到成功,取出 voice_id
while True:
q = manage("kling-voice-manage", {"op": "query", "task_id": task_id})
if q["data"]["task_status"] in ("succeed", "failed"):
break
time.sleep(3)
voice_id = q["data"]["task_result"]["voices"][0]["voice_id"]
print("voice_id:", voice_id)
# 删除(同步):manage("kling-voice-manage", {"op": "delete", "voice_id": voice_id})# -------- 元素(操作完全对称,仅模型与字段名不同)--------
# 创建元素
task = manage("kling-element-manage",
{"op": "create", "element_name": "小美",
"element_description": "一个年轻女性角色",
"frontal_image": "https://cos.example.com/frontal.jpg"})
task_id = task["data"]["task_id"]
# 轮询直到成功,取出 element_id
while True:
q = manage("kling-element-manage", {"op": "query", "task_id": task_id})
if q["data"]["task_status"] in ("succeed", "failed"):
break
time.sleep(3)
element_id = q["data"]["task_result"]["elements"][0]["element_id"]
print("element_id:", element_id)
# 删除(同步):manage("kling-element-manage", {"op": "delete", "element_id": element_id})const BASE = 'https://api-model.shuntianchuang.cn';
const HEADERS = {
Authorization: 'Bearer sk-你的令牌',
'Content-Type': 'application/json',
};
// 业务参数全部放 metadata;响应 content 是上游原始 JSON 字符串
async function manage(model, meta) {
const resp = await fetch(`${BASE}/v1/chat/completions`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model,
messages: [{ role: 'user', content: 'manage' }],
metadata: meta,
}),
});
const body = await resp.json();
return JSON.parse(body.choices[0].message.content);
}
// 创建音色
const task = await manage('kling-voice-manage', {
op: 'create',
voice_name: '小美',
voice_url: 'https://cos.example.com/reference.wav',
});
const taskId = task.data.task_id;
// 轮询直到成功,取出 voice_id
let q;
while (true) {
q = await manage('kling-voice-manage', { op: 'query', task_id: taskId });
if (q.data.task_status === 'succeed' || q.data.task_status === 'failed')
break;
await new Promise((r) => setTimeout(r, 3000));
}
const voiceId = q.data.task_result.voices[0].voice_id;
console.log('voice_id:', voiceId);
// 删除(同步):await manage('kling-voice-manage', { op: 'delete', voice_id: voiceId });// -------- 元素(操作完全对称,仅模型与字段名不同)--------
// 创建元素
const task2 = await manage('kling-element-manage', {
op: 'create',
element_name: '小美',
element_description: '一个年轻女性角色',
frontal_image: 'https://cos.example.com/frontal.jpg',
});
const taskId2 = task2.data.task_id;
// 轮询直到成功,取出 element_id
let q2;
while (true) {
q2 = await manage('kling-element-manage', { op: 'query', task_id: taskId2 });
if (q2.data.task_status === 'succeed' || q2.data.task_status === 'failed')
break;
await new Promise((r) => setTimeout(r, 3000));
}
const elementId = q2.data.task_result.elements[0].element_id;
console.log('element_id:', elementId);
// 删除(同步):await manage('kling-element-manage', { op: 'delete', element_id: elementId });管理操作免费;平台不提供元素 / 音色列表接口,请自行保存 element_id / voice_id;删除后不可再引用;试听地址为临时链接,请及时下载转存。
#在生成请求中引用
第二步:在生成请求中引用——素材引用统一写在 metadata.contents 数组里,一项对应一个素材:
| contents 项 | 对应素材 | prompt 里怎么引用 |
|---|---|---|
{"type":"element","element_id":"…"} | 1 个元素 | @元素名(即创建时的 element_name) |
{"type":"voice","voice_id":"…","id":"narr"} | 1 个音色 | @索引(即 contents 项的 id,自取标签,如 narr、v1) |
规则:
- 数量上限:元素 ≤ 3(仅 v3 / v3-omni / o1)、音色 ≤ 2(v2.6 / v3 / omni 系)。
- 引用音色时必须带
audio(v2.6 / v3 用native,omni / o1 可native/original):音色要出声,无声视频不支持音色,不满足会在提交前返回 400 提示补上。 - 元素 prompt 用
@元素名,音色 prompt 用@索引,两套引用不要混用;多个元素名避免互为前缀(如@Zhang与@ZhangSan)。
单元素 / 单音色:
# v2.6 图生视频 + 音色:prompt 用 @索引 引用音色说话,audio 须带 native
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-video-v2.6",
"prompt": "@narr 对着镜头微笑着说:你好,欢迎体验。",
"image": "https://example.com/face.png",
"audio": "native",
"metadata": {
"contents": [{"type": "voice", "voice_id": "929463831049801748", "id": "narr"}]
}
}'# v3 图生视频 + 元素:prompt 用 @元素名 引用(即创建时的 element_name)
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-video-v3",
"prompt": "@小美 自然转头并对镜头微笑,镜头缓慢推近",
"image": "https://example.com/face.png",
"duration": 3,
"metadata": {
"contents": [{"type": "element", "element_id": "321601259306151"}]
}
}'import requests
BASE = "https://api-model.shuntianchuang.cn"
HEADERS = {"Authorization": "Bearer sk-你的令牌", "Content-Type": "application/json"}
# v2.6 图生视频 + 音色:prompt 用 @索引 引用音色说话,audio 须带 native
requests.post(f"{BASE}/kling/v1/videos/image2video", headers=HEADERS, json={
"model": "kling-video-v2.6",
"prompt": "@narr 对着镜头微笑着说:你好,欢迎体验。",
"image": "https://example.com/face.png",
"audio": "native",
"metadata": {
"contents": [{"type": "voice", "voice_id": "929463831049801748", "id": "narr"}],
},
})
# v3 图生视频 + 元素:prompt 用 @元素名 引用(即创建时的 element_name)
requests.post(f"{BASE}/kling/v1/videos/image2video", headers=HEADERS, json={
"model": "kling-video-v3",
"prompt": "@小美 自然转头并对镜头微笑,镜头缓慢推近",
"image": "https://example.com/face.png",
"duration": 3,
"metadata": {
"contents": [{"type": "element", "element_id": "321601259306151"}],
},
})
# 提交后按「查询与下载」页的流程轮询 task_id 获取视频const BASE = 'https://api-model.shuntianchuang.cn';
const HEADERS = {
Authorization: 'Bearer sk-你的令牌',
'Content-Type': 'application/json',
};
// v2.6 图生视频 + 音色:prompt 用 @索引 引用音色说话,audio 须带 native
await fetch(`${BASE}/kling/v1/videos/image2video`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model: 'kling-video-v2.6',
prompt: '@narr 对着镜头微笑着说:你好,欢迎体验。',
image: 'https://example.com/face.png',
audio: 'native',
metadata: {
contents: [{ type: 'voice', voice_id: '929463831049801748', id: 'narr' }],
},
}),
});
// v3 图生视频 + 元素:prompt 用 @元素名 引用(即创建时的 element_name)
await fetch(`${BASE}/kling/v1/videos/image2video`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model: 'kling-video-v3',
prompt: '@小美 自然转头并对镜头微笑,镜头缓慢推近',
image: 'https://example.com/face.png',
duration: 3,
metadata: {
contents: [{ type: 'element', element_id: '321601259306151' }],
},
}),
});
// 提交后按「查询与下载」页的流程轮询 task_id 获取视频#多元素 / 多音色
多元素 / 多音色:contents 数组多写一项即可——一段双音色的 contents(v2.6 图生视频,两个人物对话):
"contents": [
{"type": "voice", "voice_id": "929463831049801748", "id": "narr"},
{"type": "voice", "voice_id": "929477316815110196", "id": "guest"}
]prompt 里用 @narr、@guest 分别指定谁说哪句台词:
# 双音色对话(v2.6 图生视频)
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-video-v2.6",
"prompt": "@narr 开场说:大家好。随后 @guest 回答:很高兴见到你。",
"image": "https://example.com/two-people.png",
"audio": "native",
"metadata": {
"contents": [
{"type": "voice", "voice_id": "929463831049801748", "id": "narr"},
{"type": "voice", "voice_id": "929477316815110196", "id": "guest"}
]
}
}'# 双元素同框(v3 图生视频):contents 里多写一个元素项,prompt 用 @元素名 指定谁出场
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/image2video \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-video-v3",
"prompt": "@小美 和 @小明 面对面握手,镜头环绕",
"image": "https://example.com/scene.png",
"duration": 5,
"metadata": {
"contents": [
{"type": "element", "element_id": "321601259306151"},
{"type": "element", "element_id": "321667483392215"}
]
}
}'# 双音色对话(v2.6 图生视频)
requests.post(f"{BASE}/kling/v1/videos/image2video", headers=HEADERS, json={
"model": "kling-video-v2.6",
"prompt": "@narr 开场说:大家好。随后 @guest 回答:很高兴见到你。",
"image": "https://example.com/two-people.png",
"audio": "native",
"metadata": {
"contents": [
{"type": "voice", "voice_id": "929463831049801748", "id": "narr"},
{"type": "voice", "voice_id": "929477316815110196", "id": "guest"},
],
},
})
# 双元素同框(v3 图生视频)
requests.post(f"{BASE}/kling/v1/videos/image2video", headers=HEADERS, json={
"model": "kling-video-v3",
"prompt": "@小美 和 @小明 面对面握手,镜头环绕",
"image": "https://example.com/scene.png",
"duration": 5,
"metadata": {
"contents": [
{"type": "element", "element_id": "321601259306151"},
{"type": "element", "element_id": "321667483392215"},
],
},
})// 双音色对话(v2.6 图生视频)
await fetch(`${BASE}/kling/v1/videos/image2video`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model: 'kling-video-v2.6',
prompt: '@narr 开场说:大家好。随后 @guest 回答:很高兴见到你。',
image: 'https://example.com/two-people.png',
audio: 'native',
metadata: {
contents: [
{ type: 'voice', voice_id: '929463831049801748', id: 'narr' },
{ type: 'voice', voice_id: '929477316815110196', id: 'guest' },
],
},
}),
});
// 双元素同框(v3 图生视频)
await fetch(`${BASE}/kling/v1/videos/image2video`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model: 'kling-video-v3',
prompt: '@小美 和 @小明 面对面握手,镜头环绕',
image: 'https://example.com/scene.png',
duration: 5,
metadata: {
contents: [
{ type: 'element', element_id: '321601259306151' },
{ type: 'element', element_id: '321667483392215' },
],
},
}),
});#素材直通与视频编辑
metadata.contents 除了元素 / 音色,也接受直通素材项,metadata.options 承接任务选项:
| 位置 | 说明 |
|---|---|
contents {"type":"base_video","url":"…"} | 待编辑的底视频(omni 编辑场景),同类还支持 feature_video / refer_image |
metadata.options.external_task_id | 自定义任务 ID(等价顶层 external_task_id) |
metadata.options.watermark_info | {"enabled": true} 开启「AI生成」水印(不传默认无水印) |
最常用场景——omni 编辑一段已有视频(底视频 + 保留原声):
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/text2video \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-video-v3-omni",
"prompt": "把画面整体色调调成黄昏暖色,其他内容保持不变",
"size": "1280x720",
"audio": "original",
"duration": 5,
"metadata": {
"contents": [{"type": "base_video", "url": "https://cos.example.com/input.mp4"}]
}
}'import requests
BASE = "https://api-model.shuntianchuang.cn"
HEADERS = {"Authorization": "Bearer sk-你的令牌", "Content-Type": "application/json"}
requests.post(f"{BASE}/kling/v1/videos/text2video", headers=HEADERS, timeout=300, json={
"model": "kling-video-v3-omni",
"prompt": "把画面整体色调调成黄昏暖色,其他内容保持不变",
"size": "1280x720",
"audio": "original",
"duration": 5,
"metadata": {
"contents": [{"type": "base_video", "url": "https://cos.example.com/input.mp4"}],
},
})
# 提交后按「查询与下载」页的流程轮询 task_id 获取视频const BASE = 'https://api-model.shuntianchuang.cn';
const HEADERS = {
Authorization: 'Bearer sk-你的令牌',
'Content-Type': 'application/json',
};
await fetch(`${BASE}/kling/v1/videos/text2video`, {
method: 'POST',
headers: HEADERS,
body: JSON.stringify({
model: 'kling-video-v3-omni',
prompt: '把画面整体色调调成黄昏暖色,其他内容保持不变',
size: '1280x720',
audio: 'original',
duration: 5,
metadata: {
contents: [
{ type: 'base_video', url: 'https://cos.example.com/input.mp4' },
],
},
}),
});
// 提交后按「查询与下载」页的流程轮询 task_id 获取视频编辑视频(base_video / feature_video)时请显式传 size 指定输出画幅(如 1280x720,与底视频一致):不传时输出画幅默认 16:9 而非跟随原视频。audio: "original"(保留原声)要求参考视频自带音轨;本站文生视频默认无声,做二次编辑时建议选用带音轨的源素材。
素材 URL 必须是公网可直接下载的直链(图片 jpg/jpeg/png ≤ 50MB、宽高 ≥ 300px;音频 ≥ 5 秒;视频 mp4/mov ≤ 200MB)。实测正规站点直链一般可拉取(自有站点、主流对象存储等),但个别站点会被上游拉取失败(实测 w3school.com.cn、海外图床 wikimedia 等会失败,图片/音频素材失败不扣费),遇到「拉取素材失败」请更换素材源重试。特别注意:base_video 等视频素材拉取失败时任务不报错、仍按编辑价计费,但产出内容与底视频无关——编辑前请先自查链接可达(本站成片链接约 45 分钟失效,不能直接当底视频二次编辑)。推荐优先使用自有域名直链,或先经本站生成再引用产物链接(产物直链,最稳定),或 Base64 传入。
