提交任务(可灵统一格式)
可灵统一格式的视频生成为异步任务:POST /v1/videos 提交 → 查询与下载 拿成片直链。15 个模型共用本端点,选型见模型指南。鉴权与站点其他接口一致:请求头携带 Authorization: Bearer 你的令牌(见接入地址与鉴权)。
NOTE
参数缺省:duration 缺省 5 秒、resolution 缺省 720p、aspect_ratio 缺省 16:9、audio 缺省 off(静音,即该模型最低价档)——想要声音必须显式传 metadata.audio。提交前网关会按模型校验参数,非法组合直接返回 400 并附合法取值提示,按提示修正即可。
端点
POST /v1/videos
请求体为 JSON;也接受 multipart 表单(图片文件走 input_reference 字段,metadata 以 JSON 字符串传入),见multipart 文件上传。
请求体
以下两个参数为旧写法兼容,建议尽量使用新写法(分辨率用 resolution、画幅用 aspect_ratio):
metadata 内也可传以下顶层参数的备选位置:顶层未传时生效,优先级不如顶层,建议在顶层传递。
metadata.contents 素材通道
contents 是数组,每项形如 {"type": "<类型>", …}:
约束:
- 文生视频(无
image、无首尾帧)携带其余素材项 → 400(全能系 kling-3.0-omni / kling-o1 除外,可只带素材直引,见引用元素与音色);
- 动作控制任务的素材必须恰好一张形象图(
image)+ 一段动作参考视频(video),动作视频须包含清晰的人物动作(人物过小、缺少上半身会被拒绝,任务失败并回显原因);
- 素材 URL 均须公网可访问(http / https)。
参数优先级
同一参数多处传值时,按以下优先级取值:
duration:顶层(含 seconds)> metadata.duration > 缺省 5;
resolution:顶层 > metadata.resolution > mode 别名 > 缺省 720p;
aspect_ratio:顶层 > metadata.aspect_ratio > size 推断 > 缺省 16:9。
请求示例
以下场景按需取用,完整参数说明见上文请求体。
文生视频
只传 model + prompt,三档全缺省(720p / 5 秒 / 静音):
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0",
"prompt": "一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近"
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-你的令牌",
"Content-Type": "application/json",
},
json={
"model": "kling-3.0",
"prompt": "一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近",
},
)
task = resp.json()
print(task["id"], task["status"]) # 记住 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-3.0',
prompt: '一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近',
}),
});
const task = await resp.json();
console.log(task.id, task.status); // 记住 id 用于查询
图生视频
传 image 即图生视频,prompt 可省略;resolution 按需指定:
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-2.5-turbo",
"prompt": "镜头缓缓推进,猫转头看向镜头",
"resolution": "1080p",
"image": "https://example.com/first-frame.jpg"
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-你的令牌",
"Content-Type": "application/json",
},
json={
"model": "kling-2.5-turbo",
"prompt": "镜头缓缓推进,猫转头看向镜头",
"resolution": "1080p",
"image": "https://example.com/first-frame.jpg",
},
)
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-2.5-turbo',
prompt: '镜头缓缓推进,猫转头看向镜头',
resolution: '1080p',
image: 'https://example.com/first-frame.jpg',
}),
});
const task = await resp.json();
console.log(task.id);
首尾帧生视频
统一推荐写法:顶层 image 承担首帧,contents.last_frame 承担尾帧。 尾帧必须与首帧同时提供;首尾帧任务画幅跟随素材(aspect_ratio 被忽略),v2.5 / v2.6 系自动按 1080p 生成,成片从首帧画面平滑过渡到尾帧画面:
# 场景一:推荐写法(顶层 image 首帧 + contents.last_frame 尾帧)
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-2.6",
"prompt": "从清晨的窗台过渡到黄昏的海边,镜头缓慢横移",
"image": "https://example.com/first.jpg",
"metadata": {
"contents": [
{ "type": "last_frame", "url": "https://example.com/last.jpg" }
]
}
}'
# 场景二:兼容写法(仍须传 image;首帧按 contents.first_frame 生效,image 不参与)
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-2.6",
"prompt": "从清晨的窗台过渡到黄昏的海边,镜头缓慢横移",
"image": "https://example.com/first.jpg",
"metadata": {
"contents": [
{ "type": "first_frame", "url": "https://example.com/first.jpg" },
{ "type": "last_frame", "url": "https://example.com/last.jpg" }
]
}
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-你的令牌",
"Content-Type": "application/json",
},
json={
"model": "kling-2.6",
"prompt": "从清晨的窗台过渡到黄昏的海边,镜头缓慢横移",
# 场景一:推荐写法(顶层 image 首帧)
"image": "https://example.com/first.jpg",
"metadata": {
"contents": [
{"type": "last_frame", "url": "https://example.com/last.jpg"},
]
},
},
)
task = resp.json()
print(task["id"])
# 场景二:兼容写法(仍须传 image;contents 里补 first_frame 项,首帧按 first_frame 生效)
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-2.6',
prompt: '从清晨的窗台过渡到黄昏的海边,镜头缓慢横移',
// 场景一:推荐写法(顶层 image 首帧)
image: 'https://example.com/first.jpg',
metadata: {
contents: [{ type: 'last_frame', url: 'https://example.com/last.jpg' }],
},
}),
});
const task = await resp.json();
console.log(task.id);
// 场景二:兼容写法(仍须传 image;contents 里补 first_frame 项,首帧按 first_frame 生效)
兼容写法同样必须传顶层 image(首尾帧是图生任务,无 image 的纯 contents 帧写法两渠道均返回 400);image 与 contents.first_frame 同时提供时按 first_frame 生效,image 不参与首帧——不要依赖双传,首帧在两处二选一表达即可。
多镜头分镜
multi_shot 开启分镜:intelligence 智能分镜,或 customize 按 multi_prompt 脚本出片。仅 kling-3.0 系 / kling-3.0-omni 系支持:
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0",
"prompt": "一只猫的一天",
"metadata": {
"multi_shot": true,
"shot_type": "customize",
"multi_prompt": [
{ "index": 1, "prompt": "清晨,猫在窗台伸懒腰", "duration": 3 },
{ "index": 2, "prompt": "午后,猫在草地上追蝴蝶", "duration": 4 }
]
}
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-你的令牌",
"Content-Type": "application/json",
},
json={
"model": "kling-3.0",
"prompt": "一只猫的一天",
"metadata": {
"multi_shot": True,
"shot_type": "customize",
"multi_prompt": [
{"index": 1, "prompt": "清晨,猫在窗台伸懒腰", "duration": 3},
{"index": 2, "prompt": "午后,猫在草地上追蝴蝶", "duration": 4},
],
},
},
)
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-3.0',
prompt: '一只猫的一天',
metadata: {
multi_shot: true,
shot_type: 'customize',
multi_prompt: [
{ index: 1, prompt: '清晨,猫在窗台伸懒腰', duration: 3 },
{ index: 2, prompt: '午后,猫在草地上追蝴蝶', duration: 4 },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
动作控制
形象图 + 动作参考视频(恰好一图一视频),character_orientation 必填;成片时长跟随动作视频,请求 duration 不生效:
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": "prompt", "text": "跟随视频中的舞蹈动作" }
]
}
}'
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": "prompt", "text": "跟随视频中的舞蹈动作"},
],
},
},
)
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: 'prompt', text: '跟随视频中的舞蹈动作' },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
引用元素与音色
引用分两步:第 1 步在 metadata.contents 里声明素材,第 2 步在提示词里点名——完整规则(写法 A / 写法 B、编号规则、约束清单、动作控制引用元素示例)见元素与音色 · 在视频生成中引用。最小写法:
- 声明:元素
{"type": "element", "id": "<元素ID>"}、音色 {"type": "voice", "id": "<音色ID>"},ID 填创建终态返回的 element_id / voice_id;
- 点名:普通任务用
<<<element_N>>> / <<<voice_N>>> 占位(N 按 contents 中同类素材顺序从 1 编号),动作控制任务用 @<元素ID>(元素项另带 element_id 同值);
全能模型文生直引(kling-3.0-omni 系 / kling-o1 系)——文生任务可直接携带素材,无需首帧:
# 全能系文生直引:只带 contents 素材、无需首帧
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0-omni",
"prompt": "让 <<<element_1>>> 面向镜头,用 <<<voice_1>>> 的声音说:大家好",
"duration": 5,
"metadata": {
"audio": "native",
"contents": [
{ "type": "element", "id": "324465195791137" },
{ "type": "voice", "id": "941405858536758877" }
]
}
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-你的令牌",
"Content-Type": "application/json",
},
json={
# 占位符 <<<element_N>>> / <<<voice_N>>> 按 contents 中同类素材顺序点名
"prompt": "让 <<<element_1>>> 面向镜头,用 <<<voice_1>>> 的声音说:大家好",
"model": "kling-3.0-omni",
"duration": 5,
"metadata": {
"audio": "native",
"contents": [
{"type": "element", "id": "324465195791137"},
{"type": "voice", "id": "941405858536758877"},
],
},
},
)
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({
// 占位符 <<<element_N>>> / <<<voice_N>>> 按 contents 中同类素材顺序点名
prompt: '让 <<<element_1>>> 面向镜头,用 <<<voice_1>>> 的声音说:大家好',
model: 'kling-3.0-omni',
duration: 5,
metadata: {
audio: 'native',
contents: [
{ type: 'element', id: '324465195791137' },
{ type: 'voice', id: '941405858536758877' },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
其余模型须配首帧(图生 + 素材引用)——非全能模型的文生任务不能携带素材,传 image 走图生即可,contents 里只声明元素 / 音色,首帧由 image 自动承担:
# 普通模型引用素材:必须配首帧(image 承担首帧,contents 只声明元素 / 音色)
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-3.0",
"prompt": "<<<element_1>>> 在咖啡店落座,<<<voice_1>>> 轻声说:今天天气不错",
"image": "https://example.com/scene.jpg",
"duration": 5,
"metadata": {
"audio": "native",
"contents": [
{ "type": "element", "id": "324465195791137" },
{ "type": "voice", "id": "941405858536758877" }
]
}
}'
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={
"Authorization": "Bearer sk-你的令牌",
"Content-Type": "application/json",
},
json={
# 占位符 <<<element_N>>> / <<<voice_N>>> 按 contents 中同类素材顺序点名
"prompt": "<<<element_1>>> 在咖啡店落座,<<<voice_1>>> 轻声说:今天天气不错",
"model": "kling-3.0",
"image": "https://example.com/scene.jpg",
"duration": 5,
"metadata": {
"audio": "native",
"contents": [
{"type": "element", "id": "324465195791137"},
{"type": "voice", "id": "941405858536758877"},
],
},
},
)
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({
// 占位符 <<<element_N>>> / <<<voice_N>>> 按 contents 中同类素材顺序点名
prompt: '<<<element_1>>> 在咖啡店落座,<<<voice_1>>> 轻声说:今天天气不错',
model: 'kling-3.0',
image: 'https://example.com/scene.jpg',
duration: 5,
metadata: {
audio: 'native',
contents: [
{ type: 'element', id: '324465195791137' },
{ type: 'voice', id: '941405858536758877' },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
动作控制任务引用元素(写法 B:@<元素ID> 点名,元素项带 id + element_id 同值)的完整写法与示例见元素与音色 · 在视频生成中引用。
引用相关的提交 400 速查(error_code 均为 invalid_contents / motion_contents_invalid,包络形态见错误处理):
multipart 文件上传
表单字段与 JSON 参数同名;图片文件放 input_reference,metadata 以 JSON 字符串传入:
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-你的令牌" \
-F model=kling-2.5-turbo \
-F prompt=镜头缓缓推进 \
-F duration=5 \
-F input_reference=@first-frame.jpg
import requests
resp = requests.post(
"https://api-model.shuntianchuang.cn/v1/videos",
headers={"Authorization": "Bearer sk-你的令牌"},
data={
"model": "kling-2.5-turbo",
"prompt": "镜头缓缓推进",
"duration": 5,
# metadata 以 JSON 字符串传入
# 'metadata': '{"audio": "native"}'
},
files={"input_reference": open("first-frame.jpg", "rb")},
)
task = resp.json()
print(task["id"])
import fs from 'node:fs';
const form = new FormData();
form.append('model', 'kling-2.5-turbo');
form.append('prompt', '镜头缓缓推进');
form.append('duration', '5');
// metadata 以 JSON 字符串传入:form.append('metadata', '{"audio": "native"}')
form.append(
'input_reference',
new Blob([fs.readFileSync('first-frame.jpg')]),
'first-frame.jpg',
);
const resp = await fetch('https://api-model.shuntianchuang.cn/v1/videos', {
method: 'POST',
headers: { Authorization: 'Bearer sk-你的令牌' },
body: form,
});
const task = await resp.json();
console.log(task.id);
响应体
WARNING
提交响应的 status 是提交通道的统一词表(queued / in_progress / completed / failed),与查询接口的 QUEUED / IN_PROGRESS / SUCCESS / FAILURE 不是同一套;任务是否完成一律以查询接口为准。提交响应不含成片地址。
响应示例
{
"id": "task_xxxxxxxx",
"object": "video",
"model": "kling-3.0",
"status": "queued",
"progress": 0,
"created_at": 1792992894
}
错误处理
提交期参数错误返回 HTTP 400 与统一包络;message 内嵌 JSON,解析后 error_code 可用于程序判断:
{
"code": "fail_to_fetch_task",
"message": "{\"error_code\":\"audio_not_supported\",\"message\":\"kling-3.0-turbo 不支持 audio 参数\"}",
"data": null
}
计费说明
- 按实际生成档位计费(模型 × 时长 × 分辨率 × 音频档 × 素材档 × 音色),单价见模型广场;
audio 不传 = 静音档 = 该模型最低价;自动改档(首尾帧、audio=native、指定音色等)按实际生成档计费;
- 非 16:9 画幅(1:1 方幅等)可能按更高分辨率档计费;
- 动作控制任务成片时长跟随动作参考视频,按成片实际时长计费;
- 失败任务不计费。