Submit Task (Kling Unified Format)

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

FieldTypeRequiredDefaultDescription
modelstringYes—Model id, see the Models Guide
promptstringFor t2v—Generation prompt; optional for image-to-video (the image speaks for itself)
imagestringFor i2v—First-frame reference image, URL or Base64; present means image-to-video. Must be a string; arrays or objects return 400
input_referencestring / fileNo—Alias of image: a JSON string, or a file upload via multipart (the only file field of the request); choose one of image / input_reference
durationintegerNo5Result length in seconds, integer 3–15; supported ranges per model are in the Models Guide, out-of-range returns 400
secondsintegerNo—Legacy alias of duration; when both are present seconds wins
resolutionstringNo720p720p / 1080p / 4k (4k only on kling-3.0 / kling-3.0-omni series); validated per model, out-of-range returns 400
aspect_ratiostringNo16:916:9 / 9:16 / 1:1 / 4:3 / 3:4; first-last frame tasks follow the material's aspect (this field is ignored)
metadataobjectNo—Extended parameters, see below

The following two fields are kept for legacy compatibility — prefer the new-style fields (resolution for resolution, aspect_ratio for aspect):

FieldTypeDefaultDescription
modestring—Legacy tier alias: std = 720p, pro = 1080p; an explicit resolution takes precedence
sizestring—Size notation of the aspect (e.g. 1920x1080), only used to infer the aspect: 1024x1024 / 512x512 → 1:1, 1280x720 / 1920x1080 → 16:9, 720x1280 / 1080x1920 → 9:16, anything else → 16:9; the resolution numbers themselves are ignored

metadata Parameters

FieldTypeDefaultDescription
audiostringoffoff silent / native generated voice-over / original keep source audio. Omitting means silent = the model's cheapest tier; passing a non-off value to a model without audio support returns 400
contentsarray—Material channels, see metadata.contents Material Channels
multi_shotboolean—Multi-shot storyboard switch, only on kling-3.0 / kling-3.0-omni series
shot_typestring—customize scripted shots / intelligence smart storyboard, only effective with multi_shot=true
multi_promptarray—Per-shot content {"index": 1, "prompt": "…", "duration": 3}, only with multi_shot=true
character_orientationstring—image / video, required for motion-control models (kling-motion-*): whether the character image or the motion video is the primary reference
optionsobject—Extended options passed through (e.g. custom task id), subject to actual support

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 fieldDescription
modeSame as top-level mode: std = 720p, pro = 1080p tier alias
resolution / aspect_ratio / durationFallback positions of the same-named top-level fields

metadata.contents Material Channels

contents is an array; each item looks like {"type": "<type>", …}:

typeKeysPurposeApplies to
prompttextPrompt material item, can coexist with top-level promptAll models
first_frameurlFirst-frame image (compatibility form - prefer the top-level image field; if both are given, this item wins)i2v / omni models
last_frameurlLast-frame image, must come with the first frame; v2.5 / v2.6 last-frame tasks are forced to 1080pi2v / omni models
refer_imageurlReference image (subject reference)i2v / omni models
base_videourlReference videoOmni models only (kling-3.0-omni / kling-o1 series)
feature_videourlReference video (feature)Omni models only
videourlLegacy alias of base_videoOmni models only
imageurlCharacter reference imageMotion-control models only
elementid (optional name; motion tasks also carry element_id)Reference a created element, see Elements & Voices≤ 3 on regular tasks; motion: only kling-motion-3.0, ≤ 1
voiceidReference a created voice, see Elements & Voices≤ 2; audio must not be off when a voice is used

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):

cURL
Python
Node.js
# 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": "一只橘猫在阳光下的草地上追蝴蝶,电影感镜头,缓慢推近"
  }'

Image-to-Video

image present means image-to-video; prompt becomes optional. Set resolution as needed:

cURL
Python
Node.js
# 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"
  }'

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:

cURL
Python
Node.js
# 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" }
      ]
    }
  }'

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:

cURL
Python
Node.js
# 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 }
      ]
    }
  }'

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:

cURL
Python
Node.js
# 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": "跟随视频中的舞蹈动作" }
      ]
    }
  }'

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:

cURL
Python
Node.js
# 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" }
      ]
    }
  }'

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:

cURL
Python
Node.js
# 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" }
      ]
    }
  }'

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):

Triggermessage text
More than 3 elements元素素材最多 3 个(收到 N 个)
More than 2 voices音色素材最多 2 个(收到 N 个)
element item missing idelement 项须带 id(prompt 中用 <<<element_N>>> 引用)
voice item missing idvoice 项须带 id(prompt 中用 <<<voice_N>>> 引用)
voice given but audio absent / off指定音色时 audio 不能为空/off
t2v with contents on non-omni models文生视频不支持 contents 素材;素材引用请配合图生视频或全能模型(kling-3.0-omni / kling-o1)
motion element missing element_id or idmotion-control 的 element 项须同时带 element_id 与 id(prompt 中用 @id 引用)

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:

cURL
Python
Node.js
# 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

Response Body

FieldDescription
idTask id, used by Query & Download
objectAlways "video"
modelThe submitted model id
statusStarts at queued (lowercase; not the same vocabulary as the query endpoint)
progressStarts at 0
created_atCreation timestamp (seconds)
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
}
error_codeMeaning
model_not_foundUnknown model id
invalid_duration / invalid_resolution / invalid_aspect_ratioValue outside the model's supported set (the message lists the legal values)
audio_not_supportedThe model does not support audio (received a non-off value)
invalid_audioaudio value not in the model's legal set
invalid_contents / motion_contents_invalidInvalid material combination (e.g. t2v with materials, motion control missing image or video)
image_required / image_invalid / prompt_requiredRequired material missing or malformed
upstream_rejected / upstream_unavailableRejected by the generation service / temporarily unavailable, retry later
plugin_usage_invalidTier outside the model's billing enum (e.g. 4k on kling-2.5-turbo), blocked at submit time

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.