Video generation in the Kling Unified Format is an async task: submit via POST /v1/videos → get the direct link from Query & Download. All 15 models share this endpoint; see the Models Guide for choosing one. Authentication is the same as other endpoints: pass Authorization: Bearer your-token in the header (see Base URL & Authentication).
NOTE
Defaults: duration defaults to 5 s, resolution to 720p, aspect_ratio to 16:9, and audio to off (silent — the cheapest tier of each model). Pass metadata.audio explicitly if you want sound. The gateway validates parameters per model before submitting; invalid combinations return 400 with the legal values in the message.
Endpoint
POST /v1/videos
The body is JSON; multipart form data is also accepted (the image file goes in input_reference, metadata is passed as a JSON string), see Multipart File Upload.
Request Body
The following two fields are kept for legacy compatibility — prefer the new-style fields (resolution for resolution, aspect_ratio for aspect):
metadata also accepts the following fallback positions for top-level parameters: they apply only when the top level is absent, rank below it — prefer passing them at the top level.
metadata.contents Material Channels
contents is an array; each item looks like {"type": "<type>", …}:
Constraints:
- Text-to-video (no
image, no first/last frames) carrying any other material item → 400 (except the omni models kling-3.0-omni / kling-o1, which accept materials directly on t2v, see Element & Voice References);
- Motion-control tasks require exactly one character image (
image) + one motion-reference video (video); the motion video must contain a clear human motion (a subject too small or missing an upper body is rejected — the task fails and echoes the reason);
- All material URLs must be publicly reachable (http / https).
Parameter Precedence
When the same parameter is passed in several places, this order applies:
duration: top level (incl. seconds) > metadata.duration > default 5;
resolution: top level > metadata.resolution > mode alias > default 720p;
aspect_ratio: top level > metadata.aspect_ratio > size inference > default 16:9.
Request Examples
Pick the scenario you need; full parameter reference is in Request Body above.
Text-to-Video
Only model + prompt, all three tiers at defaults (720p / 5 s / silent):
# Text-to-video with defaults (720p / 5 s / silent); Chinese prompt works best for the upstream model
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token",
"Content-Type": "application/json",
},
json={
# Chinese prompt works best for the upstream model
"prompt": "一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近",
"model": "kling-3.0",
},
)
task = resp.json()
print(task["id"], task["status"]) # keep the id for polling
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({
// Chinese prompt works best for the upstream model
prompt: '一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近',
model: 'kling-3.0',
}),
});
const task = await resp.json();
console.log(task.id, task.status); // keep the id for polling
Image-to-Video
image present means image-to-video; prompt becomes optional. Set resolution as needed:
# Image-to-video; Chinese prompt works best for the upstream model
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token",
"Content-Type": "application/json",
},
json={
# Chinese prompt works best for the upstream model
"prompt": "镜头缓缓推进,猫转头看向镜头",
"model": "kling-2.5-turbo",
"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-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Chinese prompt works best for the upstream model
prompt: '镜头缓缓推进,猫转头看向镜头',
model: 'kling-2.5-turbo',
resolution: '1080p',
image: 'https://example.com/first-frame.jpg',
}),
});
const task = await resp.json();
console.log(task.id);
First-Last Frame Video
Recommended form: top-level image carries the first frame, contents.last_frame carries the last frame. The last frame must come with the first frame; the aspect follows the material (aspect_ratio is ignored), v2.5 / v2.6 are forced to 1080p, and the video transitions from the first-frame scene to the last-frame scene:
# Case 1: recommended (top-level image first frame + contents.last_frame)
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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" }
]
}
}'
# Case 2: compatibility form (image still required; contents.first_frame wins, image unused)
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token",
"Content-Type": "application/json",
},
json={
"model": "kling-2.6",
# Chinese prompt works best for the upstream model
"prompt": "从清晨的窗台过渡到黄昏的海边,镜头缓慢横移",
# Case 1: recommended (top-level image first frame)
"image": "https://example.com/first.jpg",
"metadata": {
"contents": [
{"type": "last_frame", "url": "https://example.com/last.jpg"},
]
},
},
)
task = resp.json()
print(task["id"])
# Case 2: compatibility form (image still required; add a first_frame item to
# contents - the first frame then follows contents.first_frame)
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-2.6',
// Chinese prompt works best for the upstream model
prompt: '从清晨的窗台过渡到黄昏的海边,镜头缓慢横移',
// Case 1: recommended (top-level image first frame)
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);
// Case 2: compatibility form (image still required; add a first_frame item to
// contents - the first frame then follows contents.first_frame)
The compatibility form also requires the top-level image (first-last frame is an i2v task; frame items in contents without image are rejected with 400 on both channels). When image and contents.first_frame are both given, first_frame wins and image is not used as the first frame - do not rely on dual submission; express the first frame in exactly one place.
Multi-Shot
multi_shot enables storyboarding: intelligence for smart shots, or customize to script shots via multi_prompt. Only kling-3.0 / kling-3.0-omni series:
# Multi-shot storyboarding; Chinese prompts work best for the upstream model
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token",
"Content-Type": "application/json",
},
json={
# Chinese prompts work best for the upstream model
"prompt": "一只猫的一天",
"model": "kling-3.0",
"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-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Chinese prompts work best for the upstream model
prompt: '一只猫的一天',
model: 'kling-3.0',
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);
Motion Control
One character image + one motion-reference video (exactly one of each); character_orientation is required. The result duration follows the motion video — the requested duration is ignored:
# Motion control: exactly one image + one video; Chinese prompt works best for the upstream model
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": "prompt", "text": "跟随视频中的舞蹈动作" }
]
}
}'
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"},
# Chinese prompt works best for the upstream model
{"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-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' },
// Chinese prompt works best for the upstream model
{ type: 'prompt', text: '跟随视频中的舞蹈动作' },
],
},
}),
});
const task = await resp.json();
console.log(task.id);
Element & Voice References
Referencing takes two steps: step 1 declares the material in metadata.contents, step 2 names it in the prompt — the full rules (notations A / B, numbering rules, constraints, motion-control element example) live in Elements & Voices · Referencing in Video Generation. Minimal usage:
- Declare: element
{"type": "element", "id": "<elementId>"}, voice {"type": "voice", "id": "<voiceId>"}; the IDs are the element_id / voice_id from the creation terminal state;
- Name: regular tasks use
<<<element_N>>> / <<<voice_N>>> placeholders (numbered by same-type order in contents), motion-control tasks use @<elementId> (the element item also carries element_id with the same value);
Omni models reference directly on t2v (kling-3.0-omni / kling-o1 series) — a text-to-video task can carry materials without a first frame:
# Omni models: t2v with contents materials directly, no first frame needed;
# Chinese prompt works best for the upstream model ("让 <<<element_1>>> 面向镜头…说:大家好"
# ≈ "Have [element 1] face the camera and say hello in the voice of [voice 1]")
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token",
"Content-Type": "application/json",
},
json={
# Chinese prompt works best for the upstream model; <<<element_N>>> /
# <<<voice_N>>> name materials by their order among the same type in 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-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Chinese prompt works best for the upstream model; <<<element_N>>> /
// <<<voice_N>>> name materials by their order among the same type in 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);
Other models need a first frame (i2v + material references) — t2v on non-omni models cannot carry materials. Pass image to go image-to-video: declare only the element / voice in contents; the first frame is covered by image automatically:
# Non-omni models: a first frame is required (image covers it; contents declares element / voice);
# Chinese prompt works best for the upstream model ("<<<element_1>>> 在咖啡店落座…" ≈
# "[Element 1] sits down in a cafe; [voice 1] softly says: nice weather today")
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token",
"Content-Type": "application/json",
},
json={
# Chinese prompt works best for the upstream model; <<<element_N>>> /
# <<<voice_N>>> name materials by their order among the same type in 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-your-token',
'Content-Type': 'application/json',
},
body: JSON.stringify({
// Chinese prompt works best for the upstream model; <<<element_N>>> /
// <<<voice_N>>> name materials by their order among the same type in 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);
Motion-control element references (notation B: @<elementId> naming, element item carrying id + element_id with the same value) are detailed with an example in Elements & Voices · Referencing in Video Generation.
Reference-related submit errors (error_code is always invalid_contents / motion_contents_invalid; envelope shape see Error Handling):
Multipart File Upload
Form fields share the names of the JSON parameters; the image file goes in input_reference, and metadata is passed as a JSON string:
# Multipart upload: the image file goes in input_reference
curl -X POST https://api-model.shuntianchuang.cn/v1/videos \
-H "Authorization: Bearer sk-your-token" \
-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-your-token"},
data={
"model": "kling-2.5-turbo",
# Chinese prompt works best for the upstream model
"prompt": "镜头缓缓推进",
"duration": 5,
# metadata is passed as a JSON string:
# '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');
// Chinese prompt works best for the upstream model
form.append('prompt', '镜头缓缓推进');
form.append('duration', '5');
// metadata is passed as a JSON string: 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-your-token' },
body: form,
});
const task = await resp.json();
console.log(task.id);
Response Body
WARNING
The status of the submit response uses the submit channel's vocabulary (queued / in_progress / completed / failed), which is not the same set as the query endpoint's QUEUED / IN_PROGRESS / SUCCESS / FAILURE. Always judge completion by the query endpoint. The submit response contains no video link.
Response Example
{
"id": "task_xxxxxxxx",
"object": "video",
"model": "kling-3.0",
"status": "queued",
"progress": 0,
"created_at": 1792992894
}
Error Handling
Submit-side parameter errors return HTTP 400 with a unified envelope; message embeds JSON whose error_code is machine-readable:
{
"code": "fail_to_fetch_task",
"message": "{\"error_code\":\"audio_not_supported\",\"message\":\"kling-3.0-turbo 不支持 audio 参数\"}",
"data": null
}
Billing Notes
- Billed by the actually generated tier (model × duration × resolution × audio tier × material tier × voice); unit prices on the Model Square;
- Omitting
audio = silent tier = the model's cheapest price; auto tier changes (first-last frame, audio=native, voice tasks) are billed at the actual generated tier;
- Non-16:9 aspects (e.g. 1:1 square) may be billed at a higher resolution tier;
- Motion-control result duration follows the motion-reference video and is billed by the actual result length;
- Failed tasks are never billed.