Motion Control

Drive the figure in a "character reference image" with a "motion reference video", producing a video whose motion matches the reference; kling-video-motion-control-v3.0 can also target a custom character via an element (Element). This endpoint has no duration parameter — the output length follows the motion reference video.

Endpoints

  • Submit: POST /kling/v1/videos/text2video (shared with text-to-video; the gateway routes to the upstream motion-control endpoint by model)
  • Query: GET /kling/v1/videos/text2video/{task_id}, see Query & Download

Models: kling-video-motion-control-v3.0, kling-video-motion-control-v2.6.

Request Body

FieldTypeRequiredDescription
modelstringYesMotion-control model name (legacy model_name also works)
metadata.contentsarrayYesReference assets: exactly one character image (image) and one motion video (video), plus optional prompt and element — see the table below
metadata.character_orientationstringYesFigure orientation in the output: image (same as the character image) / video (same as the motion video)
resolutionstringNoResolution: 720p (default) / 1080p (top level or metadata)
audiostringNoSound: original (keep the reference video's audio, default) / off (top level or metadata)
metadata.optionsobjectNoGeneric options: external_task_id (custom task ID), watermark_info ({"enabled":true} for the "AI-generated" watermark)

metadata.contents items:

typeRequired fieldsDescription
prompttext (≤ 2500 chars)Text prompt; use it to add scene elements or camera moves. Avoid describing motion — motion comes from the reference video
imageurlCharacter reference image, URL or Base64. jpg / jpeg / png, ≤ 50MB, both dimensions ≥ 300px, aspect ratio 1:2.5 ~ 2.5:1
videourlMotion reference video, URL only. mp4 / mov, ≤ 100MB, dimensions 340 ~ 3850px, at least 3 seconds
elementelement_id + idReference subject (an element created via Elements & Voices); v3.0 only, at most 1; id is a label you pick, referenced in prompt as @id
NOTE

The motion video's duration cap depends on character_orientation: image — up to 10 seconds; video — up to 30 seconds. With fast or complex motion the output may be shorter than the uploaded video (the model extracts valid motion only; at least 3 contiguous seconds are needed); billing follows the output length.

Request Example

cURL
Python
Node.js
curl -X POST https://api-model.shuntianchuang.cn/kling/v1/videos/text2video \
  -H "Authorization: Bearer sk-你的令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling-video-motion-control-v3.0",
    "resolution": "720p",
    "audio": "original",
    "metadata": {
      "character_orientation": "video",
      "contents": [
        {"type": "prompt", "text": "The girl is wearing casual clothes, standing naturally"},
        {"type": "image", "url": "https://example.com/character.png"},
        {"type": "video", "url": "https://example.com/motion.mp4"}
      ]
    }
  }'
WARNING

Character image: keep the figure's proportions close to the person in the motion video (avoid driving a half-body figure with full-body motion); the figure needs a clear upper body / full body and head, unobstructed, avoiding extreme poses; real or stylized characters are supported. Motion video: prefer a single-person action (with multiple people the largest figure is used), real-human motion, one continuous shot with the character always in frame — cuts and camera moves cause truncation. Asset URLs must be publicly downloadable direct links.

Response Body

A successful submission returns the Kling-format task object (same as the Submit Task response); use data.task_id for polling. The query lifecycle, task_result.videos structure, and billing mirror (final_unit_deduction) are identical to text / image-to-video — see Query & Download.

Response Example

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

Verified behavior (v3.0, 720p + audio:"original", output in ~3 minutes): the output resolution follows the 720p tier (1264×720, framing follows the source assets), the duration follows the motion video (5.08s → 5.03s), and final_unit_deduction was 450000. The output is an upstream signed link that expires in about 45 minutes — download promptly. When the reference video itself is silent, audio:"original" output is silent too. Model names and prices follow the model marketplace; billing settles on actual usage when the task completes (failed tasks are refunded).