Kling 3.0 pro Motion Control API

kwaivgi/kling-v3.0-pro/motion-control

Kling 3.0 (pro Motion Control) transforms one character image and one reference video into identity-locked 1080p motion-transfer video, with precise action-trajectory transfer and temporal continuity. It preserves the character's facial details, clothing features, and body proportions while applying the reference video's motion range, pacing, and scene interaction.

Input

Prompt

109/2500

Reference Image

Drag and drop files, paste from clipboard, or provide a URL.

1/1 files added

Reference Video

Drag and drop files, paste from clipboard, or provide a URL.

1/1 files added

Character Orientation

Output

Ready

Continue with

Kling 3.0 std Motion Control Kling 3.0 Kling 2.6 Motion Control Seedance 2.5

Examples

@Element1 walks the runway and turns, following the motion of the reference video, elegant fashion show pace.

REST API

Quick Start

Authenticate, submit a valid input object, then use task_id to retrieve the video.

Connect to the Vidgo API

Create an API key, keep it only on your server, and send Authorization: Bearer VIDGO_API_KEY.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one generation task

Run the smallest valid payload for this workflow. The model must be kwaivgi/kling-v3.0-pro/motion-control. A successful submission immediately returns task_id without waiting for the video.

Submit request

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "kwaivgi/kling-v3.0-pro/motion-control",
  "input": {
    "prompt": "@Element1 walks the runway and turns, following the motion of the reference video, elegant fashion show pace.",
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-image.png"
    ],
    "video_urls": [
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-video.mp4"
    ],
    "character_orientation": "video",
    "resolution": "1080p",
    "kling_elements": [
      {
        "frontal_image_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-frontal.png",
        "reference_image_urls": [
          "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-angle-1.png"
        ]
      }
    ]
  }
}
JSON
)

RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Wait for the result

Query with task_id, continue for not_started/running, and stop for finished/failed. On success, read data.files[].file_url.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll about every 2 seconds, then back off gradually. Continue only for not_started or running and stop on finished or failed. You can instead add callback_url to the same top-level request contract.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "running",
    "created_time": "2026-03-11T04:23:18Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [
      {
        "file_url": "https://storage.vidgo.ai/generated/video.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

Complete runnable example

Expand for a complete script with HTTP and business-code checks, task_id validation, polling, terminal-state handling, and a timeout boundary.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "kwaivgi/kling-v3.0-pro/motion-control",
  "input": {
    "prompt": "@Element1 walks the runway and turns, following the motion of the reference video, elegant fashion show pace.",
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-image.png"
    ],
    "video_urls": [
      "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/input-video.mp4"
    ],
    "character_orientation": "video",
    "resolution": "1080p",
    "kling_elements": [
      {
        "frontal_image_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-frontal.png",
        "reference_image_urls": [
          "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/motion-control/v1/01/element-angle-1.png"
        ]
      }
    ]
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Input parameters

These are the fields accepted inside input. The request example shows the required top-level model field.

Field	Type	Required	Default	Description
prompt	string	No	—	Optional; null, empty, and whitespace-only prompts are treated as omitted. Nonempty text is trimmed and limited to 2,500 characters.
image_urls	array	Yes	—	Reference image URL array. Only one image is supported. Supports JPG, JPEG, PNG, max 10MB.
video_urls	array	Yes	—	Reference video URL array. Only one video is supported. Supports MP4, MOV, max 100MB.
character_orientation	string	Yes	—	Character orientation mode. image or video.
resolution	string	No	1080p	Output resolution. This model ID accepts 1080p only. Do not send resolution to switch tiers.
kling_elements	array	No	—	Optional facial consistency element definitions. Only available when character_orientation is video. Only 1 element is supported and can be referenced in the prompt as @Element1. When an element is provided, both frontal_image_url and reference_image_urls are required.

Response Fields

Submission returns task identity immediately. Status responses add progress, every output file, or a failure message.

Field	Type	Description
code	integer	Application result code; successful responses use 0 or 200.
message	string	Human-readable message or error detail when present.
data.task_id	string	Task ID used in the status endpoint path.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	integer	Task progress from 0 to 100, when included in the response.
data.files[]	array	All output files from a successful task, in response order.
data.files[].file_url	string	Public URL for a generated video.
data.files[].file_type	string	File type, such as video.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal alternatives; stop polling when either is returned.

not_started
The task was accepted and is waiting to begin.
running
Generation is in progress. Continue polling the same task_id.
finished
Generation succeeded. Read every video URL from data.files[].file_url.
failed
Generation stopped with an error. Read data.error_message and stop polling.

Polling and Errors

AuthenticationA 401 response means the Bearer API key is missing or invalid. Correct it before retrying.
ValidationA 400 response identifies an invalid field, unsupported media key, or insufficient credit balance. Correct the request before resubmitting.
Network and timeoutA transport failure is different from a failed task. Retry status checks with a bounded timeout before deciding that the task failed.
Polling intervalStart around every 2 seconds and increase the interval gradually for a long-running task.
Terminal statesContinue only for not_started or running. Stop immediately on finished or failed.
Callback optionProvide callback_url at the request top level to receive the final flat task object; polling remains available if delivery fails.

Endpoint limits

Specification	Value	Details
Input mode	1 image + 1 video	image_urls and video_urls each require exactly one URL. prompt is optional.
Output	Video task	The endpoint returns an asynchronous task ID.
Resolution	1080p	Fixed by model ID kwaivgi/kling-v3.0-pro/motion-control. Do not send resolution to switch tiers.
Reference duration	3–10s / 3–30s	image orientation: 3–10 seconds. video orientation: 3–30 seconds. Do not send duration; the backend probes the file.
Billing basis	15 credits/sec	Credits = ceil(detected seconds × 15); multiply by the per-second rate before rounding the total credits up.

View Kling 3.0 pro Motion Control API documentation

Kling 3.0 pro Motion Control

Key Features of Kling 3.0 Motion Control API

Identity-Locked Animation From Reference VideoKling 3.0 Motion Control is built for teams that need a fixed and dependable transfer pattern: one reference image anchors the character, and one reference video drives the performance. That structure makes identity-locked animation more predictable for branded characters, repeat talent, and commercial campaigns where visual continuity matters. Exactly one image and one video. Identity stays anchored to the source image. Reference-driven transfer for repeatable output.
1080p Output With Kinetic Precisionpro Motion Control delivers fixed 1080p output with clear per-second pricing for commercial review and client delivery. Keep the same one-image-plus-one-video contract while raising fidelity for campaigns, previs reviews, and finished assets. 1080p for delivery. Per-second pricing by reference-video duration. Sharper output for commercial workflows.
Prompt-Guided Scene Control and Orientation ModesThe current endpoint keeps the interface disciplined while still giving teams meaningful control. You can add an optional scene prompt, choose character_orientation as image or video, and use the reference clip to steer action style without expanding the request shape into a harder-to-manage creative toolchain. Optional scene prompt for context shaping. character_orientation supports image or video. Simple request contract for app integration.
Camera-Directed Workflows With Temporal ConsistencyKling 3.0 Motion Control is especially useful when teams need temporal consistency inside camera-directed production workflows. By grounding animation in a real reference performance, it becomes easier to previs shot rhythm, evaluate character staging, and keep kinetic behavior believable before larger edit or VFX steps begin. Reference performance improves temporal consistency. Useful for previs and staging reviews. Supports camera-led production planning.
Part of Kling 3.0's Elite Control StackPart of Kling 3.0's elite control stack, this endpoint is designed to fit advanced cinematography workflows without pretending to be the entire control surface. It should be understood as the foundational transfer engine, while tools such as first/last-frame planning or broader creative control live in adjacent Kling 3 workflows. Foundational engine inside broader Kling workflows. Fits advanced cinematography planning stacks. Keeps endpoint scope clean and production-ready.
Standard ControlThe Standard endpoint is built for fast 720p iteration with one reference image and one reference video. It is the leanest way to test identity-locked animation, tune kinetic precision, and validate controlled transfer before moving into higher-fidelity delivery.
Professional ControlThe Pro endpoint centers on 1080p output for teams that need stronger visual fidelity, cleaner commercial delivery, and production-ready temporal consistency. It keeps the same controlled input contract while raising quality for client-facing work.
Integration with broader Kling workflowsUse Kling 3.0 Motion Control as a motion-transfer engine inside a broader Kling 3 planning stack. It fits teams that pair reference-driven animation with adjacent camera-directed workflows, cinematic planning, and high-stakes review pipelines.

Parameters

Parameter	Requirement	Description
prompt	Optional	Optional; null, empty, and whitespace-only prompts are treated as omitted. Nonempty text is trimmed and limited to 2,500 characters.
image_urls	Required	Reference image URL array. Only one image is supported. Supports JPG, JPEG, PNG, max 10MB, dimensions 340px-3850px, aspect ratio 1:2.5 to 2.5:1.
video_urls	Required	Reference video URL array. Only one video is supported. Supports MP4, MOV, max 100MB. Reference video length must be at least 3 seconds. When character_orientation is set to image, the reference video cannot exceed 10 seconds; when set to video, it cannot exceed 30 seconds.
character_orientation	Required	Character orientation mode. `imagevideo`
resolution	Optional	Output resolution is fixed by this model ID. Do not send resolution to switch tiers. Default`1080p`

How to Use Kling 3.0 Motion Control API on Vidgo API

Step 1: Register & Create API KeyCreate your Vidgo API account and generate an API key for Instant Access to Kling 3.0 Motion Control.
Step 2: Add Credits and Prepare 1 Image + 1 VideoTop up credits, then prepare exactly one reference image and one reference video. The minimum reference video length is 3 seconds. This Professional endpoint bills at 15 credits/sec for 1080p.
Step 3: Submit the Async RequestSend the request with your image URL, video URL, optional scene prompt, character_orientation, and output resolution. Then poll task status or use a webhook callback to retrieve the final file.

Kling 3.0 pro Motion Control Pricing

1080p: 15 credits/sec ($0.075/sec). Credits = ceil(detected seconds × 15); multiply by the per-second rate before rounding the total credits up.

Usage	Rate	Details
1080p	15 credits/sec ($0.075/sec)	Credits = ceil(detected seconds × 15); multiply by the per-second rate before rounding the total credits up.

Who Can Benefit from Kling 3.0 Motion Control API?

AI Video AppsBuild reference-driven animation features for creator products, avatar apps, and vertical video tools that need controlled transfer rather than open-ended generation. The fixed input contract is easier to productize, explain, and scale.
Creative & Previs StudiosUse Kling 3.0 Motion Control for previs, staging reviews, and character animation experiments where teams need kinetic precision and temporal consistency before committing to heavier editorial or VFX workflows.
Marketing TeamsTurn real reference performances into branded character clips for campaigns, product storytelling, and ad testing. The endpoint is especially useful when identity-locked animation matters more than broad generative variation.
Sports & Dance CoachingCreate commercial-grade demonstrations from reference footage for training, analysis, and instructional content. The transfer model preserves action style well enough for high-value breakdowns and repeatable visual education.
Avatar & Character PlatformsAnchor a recurring character to one source image and reuse reference performances across a library of clips. That makes it easier to maintain identity while expanding short-form storytelling or product-led personalization.
Motion R&D WorkflowsStudy action quality, timing, and shot behavior inside a controlled production environment. Teams exploring animation pipelines can use the endpoint as a reliable transfer benchmark before layering broader Kling 3 controls around it.

Why Use Vidgo API for Kling 3.0 pro Motion Control

Instant Access. Create your API key and start using Kling 3.0 pro Motion Control immediately.
Identity-Locked Transfer. One character image plus one reference video for controlled motion migration with temporal continuity.
1080p Commercial Fidelity. Deliver sharper client-facing motion transfer without changing the input contract.
Credits = ceil(detected seconds × 15); multiply by the per-second rate before rounding the total credits up.
Orientation Control. Choose character_orientation image or video to match fixed poses or camera-following performances.
Developer-Friendly Async API. Submit once, poll task status or use webhooks to retrieve the finished video.

Notes

Submit exactly one image in image_urls and one video in video_urls. Reference images support JPG/PNG up to 10MB; reference videos support MP4/MOV up to 100MB.
Reference video length must be at least 3 seconds. When character_orientation is image, use 3–10 seconds; when video, use 3–30 seconds.
Optional kling_elements (one facial element) is available when character_orientation is video to strengthen multi-angle face consistency.
This workflow focuses on visual motion transfer and returns picture-only video, ready for later sound design and voiceover.
Submit model must be kwaivgi/kling-v3.0-pro/motion-control. Resolution is fixed at 1080p for this model.

Related Models

Gemini Omni 1.1 Flash Text-to-Video preview

Gemini Omni 1.1 Flash Text-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Image-to-Video preview

Gemini Omni 1.1 Flash Image-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Reference-to-Video preview

Gemini Omni 1.1 Flash Reference-to-VideoGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

Gemini Omni 1.1 Flash Video Edit preview

Gemini Omni 1.1 Flash Video EditGoogle Gemini Omni 1.1 Flash video model with native audio, text-to-video, first/last-frame image-to-video, reference-image video, and 3–10 second video edit at 360p to 4K.

MiniMax H3 Max Turbo Text to Video preview

MiniMax H3 Max Turbo Text to VideoMiniMax H3 Max Turbo Text to Video turns text into coherent 5–15 second videos with synchronized native stereo audio and fast generation. It follows physical motion while rendering subtle changes in light and shadow.

MiniMax H3 Max Turbo Image to Video preview

MiniMax H3 Max Turbo Image to VideoMiniMax H3 Max Turbo Text to Video turns text into coherent 5–15 second videos with synchronized native stereo audio and fast generation. It follows physical motion while rendering subtle changes in light and shadow.

MiniMax H3 Max Text to VideoMiniMax H3 Max Text to Video turns text prompts into cinematic video with native stereo audio, faster-than-real-time generation, and precise instruction following. It renders complex camera work and physical motion with fine detail across multiple resolutions and common aspect ratios.

MiniMax H3 Max Image to VideoMiniMax H3 Max Text to Video turns text prompts into cinematic video with native stereo audio, faster-than-real-time generation, and precise instruction following. It renders complex camera work and physical motion with fine detail across multiple resolutions and common aspect ratios.

MiniMax H3 Max Reference to Video preview

MiniMax H3 Max Reference to VideoMiniMax H3 Max Text to Video turns text prompts into cinematic video with native stereo audio, faster-than-real-time generation, and precise instruction following. It renders complex camera work and physical motion with fine detail across multiple resolutions and common aspect ratios.

Wan 3.0 Prime Text-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Prime Image-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Prime Reference-to-Video preview

Wan 3.0 Prime Reference-to-VideoAlibaba Wan 3.0 Prime video model with text-to-video, image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds with optional synchronized audio.

Wan 3.0 Text-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Image-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

Wan 3.0 Reference-to-VideoAlibaba Tongyi Lab's Wan 3.0 multimodal video model with separate text-to-video, first/last-frame image-to-video, and reference-to-video workflows at 480p, 720p, or 1080p for 2 to 30 seconds.

FLUX 3 Text to VideoBlack Forest Labs FLUX 3 video model with text-to-video, image-to-video, first-last-frame, extend-video, and keyframes workflows at 720p or 1080p for 5 to 20 seconds, with optional native audio.

Kling 3.0 pro Motion Control — Frequently Asked Questions

What is the Kling 3.0 pro Motion Control API?

Kling 3.0 pro Motion Control is a Kuaishou (Kwai VGI) model for reference-driven video motion transfer. It turns one character image and one reference video into identity-locked 1080p motion-transfer video, with precise action-trajectory transfer and temporal continuity. Built for visual motion migration, it preserves facial details, clothing features, and body proportions while applying the reference clip's motion range, pacing, and scene interaction. You can call it programmatically or try it from the playground above.

How should Kling 3.0 pro Motion Control use character_orientation?

Choose image when you want the output character to keep the reference image's facing and staging, which fits fixed-subject poses and camera-led takes within a 3–10 second reference clip. Choose video when the character should follow the reference video's orientation and camera path, which suits complex full-body action and unlocks optional kling_elements for multi-angle facial detail within a 3–30 second clip.

What reference video duration does Kling 3.0 pro Motion Control accept?

Reference video length must be at least 3 seconds. When character_orientation is image, the clip can run up to 10 seconds; when it is video, the clip can run up to 30 seconds. Output length follows the probed reference-video duration, so prepare clips inside those windows before you submit.

When should I choose Kling 3.0 pro Motion Control 1080p?

Use pro Motion Control when you need sharper 1080p delivery for client review, campaign assets, and commercial handoff while keeping the same one-image-plus-one-video contract. For faster lower-cost iteration at 720p, use Kling 3.0 std Motion Control first, then move finished shots here.

How is Kling 3.0 pro Motion Control billed per second?

Credits = ceil(detected seconds × 15); multiply by the per-second rate before rounding the total credits up. For example, 5.2 seconds costs 78 credits.

How can Kling 3.0 pro Motion Control keep character consistency stable?

Start with a clear single-character image that shows face, outfit, and body proportions without obstruction, and pair it with a reference video where the full body or upper body plus head stay visible through the action. Keep one image and one video in the request, and describe scene context in the optional prompt when you need tighter staging guidance.

How do kling_elements improve facial consistency in Kling 3.0 pro Motion Control?

When character_orientation is video, you can attach one facial consistency element through kling_elements, referenced in the prompt as @Element1. Provide both frontal_image_url and reference_image_urls for that element so multi-angle face detail stays anchored while the body follows the reference performance.

Can Kling 3.0 pro Motion Control be used for commercial projects?

Commercial use is subject to the applicable model license and Vidgo service terms. Generated videos can support client work, marketing, training materials, and professional production pipelines that need identity-locked 1080p motion transfer.