Submit Task (Kling Format)

Consistent with the Kling official API: text-to-video and image-to-video use separate endpoints, and the omni models kling-video-v3-omni / kling-video-o1 use the same pair of endpoints (the gateway routes omni requests automatically by model; query and billing stay unchanged). The motion-control models kling-video-motion-control-v3.0 / v2.6 also enter through the same endpoints (see Motion Control). Fields such as image_tail / negative_prompt / resolution work both at the top level and inside metadata. Kling-official-only fields such as cfg_scale / camera_control / static_mask / dynamic_masks are not supported upstream and are ignored.

Endpoints

  • Text-to-video: POST /kling/v1/videos/text2video
  • Image-to-video: POST /kling/v1/videos/image2video

Besides the Kling format, you can also use the generic endpoint POST /v1/video/generations (OpenAI style, see Create Video Task) and POST /v1/responses (Responses format; the artifact is rendered as a <video> tag).

Request Body

NOTE

Before submission the gateway validates resolution / duration / audio / multi_shot per model. Invalid values get an immediate 400 with the allowed values in the message — just fix them as instructed. This protects your balance: the upstream does not reject these parameters, it silently falls back to defaults and still charges.

FieldTypeRequiredDescription
modelstringYesModel name from the model marketplace, e.g. kling-video-v2.5-turbo, kling-video-v3, kling-video-v3-omni (legacy model_name also works)
promptstringYesVideo description; negative_prompt is appended into this field upstream
imagestringNoFirst-frame image for image-to-video (URL or Base64); presence of this field switches to image-to-video. jpg / jpeg / png, ≤ 50MB, both dimensions ≥ 300px
image_tailstringNoLast-frame image, same constraints as image; requires image (last-frame-only returns 400). v2.5 / v2.6 series auto-forces 1080p with a tail frame
negative_promptstringNoNegative prompt, appended into prompt upstream
durationnumber | stringNoDuration in seconds (numeric strings accepted): v2.5-turbo / v2.6 5 / 10; v3 / v3-turbo / v3-omni 3 ~ 15; o1 3 ~ 10 (text-only 5 / 10 only)
resolutionstringNoResolution: 720p / 1080p / 4k (4k only v3 / v3-omni); defaults to the upstream tier when omitted. Use this field plus audio / multi_shot for resolution/audio/multi-shot — mode no longer carries them
aspect_ratiostringNoAspect ratio 16:9 / 9:16 / 1:1, text-to-video only (image-to-video follows the image); size notation (e.g. 1920x1080) is converted automatically
audiostringNoAudio: native / original / off, see the model matrix below; cannot be off when a voice is referenced
multi_shotbooleanNoMulti-shot, v3 / v3-omni only
external_task_idstringNoCustom task ID, echoed back on query
metadataobjectNoThe fields above may also live inside metadata (duration / resolution / audio / multi_shot / aspect_ratio / image_tail / negative_prompt); the contents asset array and options are covered in Elements & Voices
modestringNoLegacy compatibility: std → 720p, pro → 1080p (only when resolution is absent); mock / test_mode return 400 (no mock implementation, blocked to avoid real charges)
settingsobjectNoLegacy compatibility: {resolution, aspect_ratio, duration} object; lower priority than explicit top-level / metadata fields

Model × Parameter Matrix

ModelDurationResolutionAudiomulti_shot
kling-video-v2.5-turbo5 / 10720p / 1080p——
kling-video-v2.65 / 10720p / 1080pnative / off—
kling-video-v3-turbo3 ~ 15720p / 1080p——
kling-video-v33 ~ 15720p / 1080p / 4knative / original / off✅
kling-video-v3-omni3 ~ 15720p / 1080p / 4knative / original / off✅
kling-video-o13 ~ 10 (text-only 5/10)720p / 1080poriginal / off—

Additional constraints (verified upstream): first + last frame on v2.5 / v2.6 only supports 1080p (auto-adjusted); at most 3 elements (v3 / v3-omni / o1) and 2 voices; see Elements & Voices for creating and referencing assets.

Request Example

cURL
Python
Node.js
# Text-to-video: resolution via the resolution field
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-v2.5-turbo",
    "prompt": "一只橘猫在草地上追蝴蝶,电影感镜头,缓慢推近",
    "duration": 5,
    "aspect_ratio": "16:9",
    "resolution": "720p",
    "negative_prompt": "模糊,变形"
  }'
# Image-to-video with last frame: image / image_tail take a URL or Base64
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.5-turbo",
    "image": "https://example.com/first-frame.jpg",
    "image_tail": "https://example.com/last-frame.jpg",
    "prompt": "让画面中的猫跑起来,镜头缓慢推近"
  }'
NOTE

Legacy code keeps working unchanged: the legacy mode (std / pro), native settings object, and metadata.image_tail / metadata.negative_prompt tunnels all behave as before. Two differences: mode: "mock" is no longer available (returns 400; for zero-cost testing use the platform's self-use mode), and invalid parameter combinations now return 400 instead of being silently dropped (preventing silent default-tier charges). Legacy details: Legacy Guide (v2.5-turbo).

Response Body

A successful submission returns a task object; use data.task_id (also mirrored at the top level) for polling. task_status starts as submitted.

Response Example

{
  "code": 0,
  "message": "SUCCEED",
  "data": {
    "task_id": "task_xxxxxxxx",
    "task_status": "submitted",
    "task_status_msg": "",
    "create_time": 1790573567856,
    "update_time": 1790573567856
  },
  "task_id": "task_xxxxxxxx"
}

For status polling and downloads see Query & Download.