Kling V3.0 Motion Control API Quick Start

Kling V3.0 Motion Control lets you animate a static character image by extracting motion from a reference video and applying it frame by frame. The output preserves the character’s appearance from your image while reproducing the movement from the video — a technique called motion transfer. This guide covers the Novita AI endpoint, required inputs, key parameters, and working Python and curl examples you can run against a real API key.

When Motion Control Is the Right Tool

Motion Control is the right tool when you have two things: a static character image you want to animate, and a reference video whose motion you want to reproduce. It is different from Image-to-Video (I2V), which generates motion from a prompt. With Motion Control, the motion is copied from the reference video precisely — the output character will follow the same movement arc as the person in the reference video.

Use it when:

• You want a specific dance, walk cycle, or gesture applied to a character illustration or photo
• You need consistent, repeatable motion across different characters (same reference video, different images)
• You are building content where motion quality matters and open-ended I2V prompt results are too unpredictable

Do not use it when the motion itself is still undefined — in that case, I2V with a descriptive prompt gives you more flexibility at lower cost.

Step 1: Get Your Novita API Key

Sign up at novita.ai and generate an API key from the dashboard. New accounts receive free credits you can use to test Motion Control before committing to production volume.

Step 2: Confirm the Endpoint and Model ID

Kling V3.0 Motion Control on Novita AI uses the standard async video pattern:

Submit task:

POST https://api.novita.ai/v3/async/kling-v3.0-motion-control

Poll for result:

GET https://api.novita.ai/v3/async/task-result?task_id={task_id}

All requests require:

Authorization: Bearer YOUR_NOVITA_API_KEY
Content-Type: application/json

Full documentation: novita.ai/docs/api-reference/model-apis-kling-v3.0-motion-control

Step 3: Prepare Your Inputs

Motion Control requires two inputs: a reference image and a reference video. Getting these right is the single biggest factor in output quality.

Reference Image

This is the character whose appearance the output will preserve. Requirements:

• Formats: JPEG, PNG, JPG
• Maximum size: 10 MB
• Minimum resolution: 340px on each side
• Aspect ratio: between 2:5 and 5:2
• Character should be clearly visible, occupy more than 5% of the image area, and have no heavy occlusion (do not crop the head or body)

For best results, use an image where the character’s body proportions roughly match what is visible in the reference video. If the reference video shows a full-body dancer, use a full-body character image rather than a portrait crop.

Reference Video

This is the motion source. The character in the output will replicate the movements from this video:

• Formats: MP4, MOV
• Maximum size: 10 MB
• Duration: 3–30 seconds
• Minimum resolution: 340px on each side
• Aspect ratio: between 2:5 and 5:2
• The person in the reference video should have their full or upper body visible and unobstructed, including the head

Clear, well-lit footage with minimal background clutter transfers motion more accurately than noisy or crowded shots.

Step 4: Send Your First Request

Minimal curl request:

curl --request POST \
  --url https://api.novita.ai/v3/async/kling-v3.0-motion-control \
  --header 'Authorization: Bearer $NOVITA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "image": "https://example.com/character.jpg",
    "video": "https://example.com/reference_motion.mp4",
    "prompt": "A person performing a smooth dance routine, cinematic lighting",
    "model_name": "kling-v3.0-motion-control",
    "character_orientation": "video"
  }'

The response returns a task_id immediately:

{
  "task_id": "abc123xyz"
}

Step 5: Poll for the Result

Kling V3.0 Motion Control is asynchronous. Submit the task, then poll until the status is succeed:

curl --request GET \
  --url 'https://api.novita.ai/v3/async/task-result?task_id=abc123xyz' \
  --header 'Authorization: Bearer $NOVITA_API_KEY'

When complete, the response contains a videos array with the output URL:

{
  "task": {
    "status": "succeed"
  },
  "videos": [
    {
      "video_url": "https://cdn.novita.ai/output/abc123xyz.mp4",
      "video_url_ttl": "3600"
    }
  ]
}

Typical generation time is 30–120 seconds depending on video duration and mode. Poll every 5–10 seconds rather than hammering the endpoint.

Full Python Integration Example

This script submits a motion control task and polls until it completes:

import os
import time
import requests

API_KEY = os.environ["NOVITA_API_KEY"]
BASE_URL = "https://api.novita.ai"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_motion_control(image: str, video: str, prompt: str = "") -> str:
    payload = {
        "image": image,
        "video": video,
        "prompt": prompt,
        "model_name": "kling-v3.0-motion-control",
        "character_orientation": "video",
    }
    resp = requests.post(f"{BASE_URL}/v3/async/kling-v3.0-motion-control", json=payload, headers=HEADERS)
    resp.raise_for_status()
    return resp.json()["task_id"]


def poll_result(task_id: str, timeout: int = 300) -> str:
    deadline = time.time() + timeout
    while time.time() < deadline:
        resp = requests.get(
            f"{BASE_URL}/v3/async/task-result",
            params={"task_id": task_id},
            headers=HEADERS,
        )
        resp.raise_for_status()
        data = resp.json()
        status = data.get("task", {}).get("status")
        if status == "succeed":
            return data["videos"][0]["video_url"]
        if status == "failed":
            raise RuntimeError(f"Task failed: {data}")
        time.sleep(8)
    raise TimeoutError(f"Task {task_id} did not complete within {timeout}s")


if __name__ == "__main__":
    image = "https://example.com/character.jpg"
    video = "https://example.com/reference_motion.mp4"

    print("Submitting task...")
    task_id = submit_motion_control(image, video, prompt="smooth dance routine, warm lighting")
    print(f"Task ID: {task_id}")

    print("Polling for result...")
    output_url = poll_result(task_id)
    print(f"Output video: {output_url}")

API Parameters Reference

Parameter	Type	Required	Description
image	string	Yes	URL of the character image to animate. See input requirements above.
video	string	Yes	URL of the reference video whose motion will be transferred.
model_name	string	Yes	Set to kling-v3.0-motion-control.
prompt	string	No	Text description of the desired motion style or scene context. Optional but can improve output quality.
character_orientation	string	No	Controls pose alignment and output duration. "video" matches the reference video orientation — better for full-body complex motions, supports up to 30s. "image" matches the character image orientation — better for camera-relative movements, fixed at 5s.

character_orientation in practice

If your reference video shows a front-facing dancer and your character image is also front-facing, "video" will give better motion transfer and supports up to 30 seconds. If the reference video has a camera that moves around the subject and your image is a fixed-angle portrait, "image" tends to reduce unwanted perspective distortion — but note it generates a fixed 5-second clip.

Standard vs. Pro: Which Quality Tier to Choose

Kling V3.0 Motion Control is available in two quality tiers:

Standard outputs at 720p. It is the right choice for iteration, testing motion compatibility, or generating drafts before committing to a final version.

Pro outputs at 1080p with improved motion fidelity and subject consistency. Use Pro when:

• The output is going into a finished production (social post, short film, product demo)
• Fine detail in the character’s face or clothing matters
• You are generating longer clips (10s+) where quality degradation over time is more visible

For most development workflows, start with Standard to confirm input compatibility and motion quality, then switch to Pro for the final pass.

Pricing, Duration, and Cost Estimates

Novita AI bills Motion Control per second of generated video. Standard and Pro tiers have separate per-second rates. For current pricing, check the Novita AI model page.

Duration limits:

• character_orientation: "video" — up to 30 seconds
• character_orientation: "image" — fixed at 5 seconds

Cost scales with duration for "video" mode. "image" mode always generates a 5-second clip.

Troubleshooting Common Errors

Task fails immediately with a 422 or validation error Check that both image and video are publicly accessible URLs (not behind auth or a short-lived presigned URL that expired). The Novita backend must be able to fetch both files at task execution time.

Output motion looks off or the character distorts The most common cause is a mismatch between character orientation in the image and the reference video. Try switching character_orientation between "video" and "image" to see which produces better alignment.

Character loses facial identity mid-clip Ensure the character in the reference image has a clear, unobstructed face and body. For longer clips, the Pro tier maintains subject consistency better than Standard.

Reference video motion does not transfer cleanly Noisy or crowded reference footage degrades motion extraction. Use footage where the performer is the main subject against a reasonably clean background. Avoid handheld shaky footage if the goal is smooth motion transfer.

Status stuck in processing for more than 3 minutes Occasional queue delays happen. Wait up to 5 minutes before treating it as stuck. If it remains stuck, submit a fresh task — do not reuse the old task_id.

What Developers Build with Kling Motion Control

Character animation for game assets: Take a character illustration and apply a reference motion clip (walk, run, attack) without rigging or animation software.

Social content with consistent motion: Apply the same dance reference video to multiple character images to produce a series of clips with identical choreography but different looks.

Pre-visualization: Test how a specific movement sequence looks on a character design before investing in full production animation.

E-commerce product display: Apply subtle pose changes or clothing movement to product images using a carefully chosen reference video showing garment motion.

FAQ

What is the difference between Motion Control and Image-to-Video on Novita AI?

Image-to-Video (I2V) animates an image based on a text prompt — the motion is generated by the model from your description. Motion Control transfers specific motion from a reference video onto the character in your image. Motion Control gives you precise, reproducible motion; I2V gives you creative flexibility without needing a reference clip.

Does the reference video character need to match the image character’s appearance?

No. The reference video is used for motion extraction only — the output character comes from the image, not from the video. That is the core capability: motion from one source, appearance from another. The proportions should roughly match (full-body image for full-body video, portrait for upper-body video) for best transfer quality.

Can I use any publicly available video as a reference?

You can use any video that meets the format and size requirements. Motion transfers best from footage where the subject is clearly visible with minimal occlusion. Complex multi-person scenes or heavily edited footage (cuts, zooms) can reduce accuracy.

How long does generation take?

Typically 30–120 seconds depending on output duration and whether you chose Standard or Pro mode. Poll every 8–10 seconds rather than in a tight loop.

Recommended Articles

• Kling O1 on Novita AI: T2V, I2V, Ref2V, and Video Edit Modes
• Kling 3.0 Now on Novita AI: Cinematic AI Video Generation at Scale
• Kling V2.5 Turbo API on Novita AI