HopBaseThe short answer: Kling motion control takes one person image and one motion video and makes the person in the image perform the movement from the video. On HopBase you call it with the model kling-v3-motion-control (720p, 1080p, 2K or 4K) or kling-v2-6-motion-control (720p or 1080p). Both go through the same asynchronous endpoint as every other Kling model: POST https://api.hop-base.com/v1/video/generate, then poll GET /v1/video/tasks/{task_id}. Send exactly one image and one video, and leave out duration, because the output is as long as the motion video. The only extra parameter is extra.character_orientation (image or video). You are billed per second of output video, failed tasks cost nothing, and result links last 24 hours. The step that fails most often is the motion video itself: it has to show a real person's full upper body, from head to waist.
What motion control is, and when to use it instead of avatar or lip sync
Kling has three workflows that animate a person, and each one answers a different question:
| Model | Input | What moves | Output length |
|---|---|---|---|
kling-v3-motion-control / kling-v2-6-motion-control | 1 person image + 1 motion video | The whole body copies the motion in the video | Same as the motion video |
kling-avatar | 1-5 person images + 1 audio track | Face and mouth, driven by the audio | Same as the audio |
kling-lip-sync | An existing video + new audio | Only the mouth, re-synced to the new audio | Same as the source |
Use motion control when you have a movement (a dance, a product demo gesture, a walk cycle, a presenter's body language) and want a different character to perform it: a brand mascot, a model in new clothing, or a generated persona. If the character only needs to talk, use avatar or lip sync instead; our Kling digital human guide covers both.
v3 or v2.6: resolutions and list prices
Both models are billed per second of output at the rate for the resolution you request. These are the official list prices published on each model card (your actual rate depends on your group and is shown in the signed-in model catalog):
| Model | 720p | 1080p | 2K | 4K |
|---|---|---|---|---|
kling-v3-motion-control | $0.1324 / s | $0.1765 / s | $0.2647 / s | $0.3971 / s |
kling-v2-6-motion-control | $0.0735 / s | $0.1176 / s | — | — |
As a worked example, a 10-second 1080p clip on kling-v3-motion-control is 10 × $0.1765 = about $1.77 at list price. The pricing page shows the same 1080p tier in CNY (¥1.20 per second). Use v2.6 for drafts and high-volume 720p work, and v3 when you need 2K or 4K. Prices for each tier are on the kling-v3-motion-control and kling-v2-6-motion-control model cards.
Step 1: submit the task
The request goes to the same endpoint as all other Kling video. The scene decides what each input is for, so the image does not take a usage field and the video does not take a reference_type:
curl https://api.hop-base.com/v1/video/generate \
-H "Authorization: Bearer sk-YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-motion-control",
"prompt": "Copy the dance moves from the video",
"resolution": "1080p",
"images": [{ "url": "https://cdn.example.com/character.png" }],
"videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
"extra": { "character_orientation": "video" }
}'Field by field:
images: exactly one item, the person who will perform the motion.videos: exactly one item, the motion source.keep_original_sound: truekeeps the source video's audio track. Motion control does not generate any new audio.extra.character_orientation: optional,imageorvideo. The two values differ mainly in camera behavior and input length. In our test with the same person image and the same motion clip containing a 180° turn, the character turned around and showed its back in both modes.imagekeeps the framing and camera position of your person image, with an almost static background, and accepts motion videos up to 10 seconds.videolets the camera reframe and move with the motion video, and accepts motion videos up to 30 seconds. If you leave it out, HopBase sendsvideo. This is the onlyextrakey accepted for motion control; any other key returns 400.resolution:720p/1080p/2k/4kon v3,720p/1080pon v2.6. It also selects the billing tier.duration: do not send it. The length comes from the input video, and sending it returnsduration of model ... is determined by the input media; do not pass duration.
Each media item takes exactly one of url or file_id. A url must be an absolute, publicly reachable http(s) address. Relative paths, file://, private or loopback IPs, and URLs with embedded credentials are rejected at submission. A successful submit returns 202 with a task ID like kt57x….
Step 2: poll until the task finishes
curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
-H "Authorization: Bearer sk-YOUR_KEY"The status goes from queued to processing and ends at completed or failed. Only those last two are terminal, so treat anything else as still running. A completed task looks like this:
{
"id": "kt57xYOUR_TASK_ID",
"status": "completed",
"outputs": ["https://api.hop-base.com/..."],
"usage": { "bucket": "...", "billed_seconds": 10, "cost": 12.0, "cost_usd": 1.765, "currency": "CNY" }
}outputs is a signed link on api.hop-base.com that is valid for 24 hours from completion. Polling again does not extend it, so download the file to your own storage right away. usage.cost_usd is the amount actually deducted for this task. A minimal Python loop:
import time, requests
API = "https://api.hop-base.com/v1"
H = {"Authorization": "Bearer sk-YOUR_KEY"}
task = requests.post(f"{API}/video/generate", headers=H, json={
"model": "kling-v3-motion-control",
"prompt": "Copy the dance moves from the video",
"resolution": "1080p",
"images": [{"url": "https://cdn.example.com/character.png"}],
"videos": [{"url": "https://cdn.example.com/dance.mp4"}],
"extra": {"character_orientation": "video"},
}).json()
while True:
t = requests.get(f"{API}/video/tasks/{task['id']}", headers=H).json()
if t["status"] == "completed":
print(t["outputs"][0]); break
if t["status"] == "failed":
raise RuntimeError(f"{t['error'].get('code')}: {t['error']['message']}")
time.sleep(5)There is no webhook field in the Kling request contract, so polling is the only way to track a task. A task still unfinished 2 hours after creation is marked failed with error.code timeout and is not billed. Tasks cannot be cancelled.
The motion video: the step that fails most often
HopBase checks the structure of the request when you submit it: counts, field names, URL shape and resolution. Kling checks the media itself (format, size, resolution, duration and content) while the task runs. A video that does not meet the requirements is accepted and then fails a few minutes later. The most common case for motion control:
error.code: reference_input_invalid
the motion reference video was rejected: no complete human upper body was detected in it;
use a video in which a real person's upper body (head to waist) is clearly visible, then submit againPractical rules for the motion video:
- Use a real person. Animals, creatures and characters that are not human will be rejected.
- Keep the head-to-waist area in frame and unobstructed for the whole clip. Tight crops, tables or props in front of the torso, and heavy motion blur all cause problems.
- Host it somewhere that serves files reliably to datacenter clients. Your own object storage or CDN is safer than free file hosts that block server IPs.
- Remember that the clip length is the output length, and so it sets the cost. Trim the video before you submit.
- Mind the length limits: the motion video can be at most 10 seconds with
character_orientation: imageand at most 30 seconds withvideo(the default). A longer clip fails about half a minute after submission witherror.codeinvalid_requestand is not billed. In our tests a 12-second clip was rejected inimagemode and produced a full 12-second result invideomode; a 31-second clip was rejected invideomode as well. - The output aspect ratio follows the person image, not the motion video. A 9:16 portrait motion video paired with a roughly 5:6 person image produced an 864×1040 result, so use a portrait person image if you want a portrait output. In
imagemode the output can be slightly shorter than the clip: a 5-second clip produced 4.8 seconds and was billed as 4 seconds.
Failed tasks are never billed, so a rejected video costs you only time.
Errors at submission
A submission error creates no task and costs nothing. The ones specific to motion control, with their exact messages:
| What you sent | error.message |
|---|---|
| Zero or two images, or no video | motion control requires exactly 1 motion video and 1 character image |
usage on the image | motion control images[0] does not accept usage; the character image role is fixed by the scene |
reference_type on the video | motion control videos[0] does not accept reference_type; the motion video role is fixed by the scene |
| Any orientation value other than image/video | extra.character_orientation must be image or video |
duration | duration of model kling-v3-motion-control is determined by the input media; do not pass duration |
A field from OpenAI's API such as size | request body does not match the JSON contract: json: unknown field "size" |
A 402 with code insufficient_balance means your available balance, minus the estimated cost of tasks already running, cannot cover this one. The hold is released when a task ends. The full error catalog is in the Kling video API docs.
Putting it into a pipeline
A typical production setup records one clean motion clip for each move, such as a product reveal, a greeting or a dance beat. You then run that clip against many character images: different models, outfits or brand characters. Each run costs the clip length times the per-second rate, so the cost is predictable. The same API key can also run Kling text-to-video, MiniMax text-to-speech for voice-over, and the chat models that write your prompts, as long as its groups include those models. Run GET /v1/models to confirm what a key can reach.
FAQ
Can I set the length of a motion control video?
No. duration must be left out, and sending it returns 400. The output is as long as the motion video you provide, so trim the source clip to control length and cost.
How long can the motion video be?
It depends on extra.character_orientation: up to 10 seconds with image, up to 30 seconds with video (the default). A longer clip fails about half a minute into the task with invalid_request and is not billed. For a longer result, split the movement into several clips, render each one and join them.
Should I use image or video for character_orientation?
The character follows turns in the motion video in both modes. Use image when you want to keep the camera position and framing of your person image, for example a locked-off product shot, and keep the clip within 10 seconds. Use video when you also want to copy the camera movement, or when the clip is longer than 10 seconds.
Does motion control generate audio?
No new audio is generated. To keep the soundtrack of your motion video, set videos[0].keep_original_sound to true. Do not put it in extra, because extra.keep_original_sound is rejected.
Why did my task fail a few minutes after it was accepted?
Kling validates media during the task, not at submission. The most common cause is a motion video without a clearly visible real human upper body (reference_input_invalid). Other causes are unreadable URLs and content moderation (input_sensitive). Failed tasks are not billed.
What is the difference between kling-v3-motion-control and kling-v2-6-motion-control?
v3 supports 720p, 1080p, 2K and 4K. v2.6 supports 720p and 1080p at a lower per-second list price ($0.0735 / s at 720p and $0.1176 / s at 1080p, against $0.1324 / s and $0.1765 / s on v3). The request format is the same for both.
How long can I download the result?
24 hours from the moment the task completes. Polling again returns the same link without extending it, and an expired link returns 410.
How do I get access?
Create an API key in the HopBase console with a group that includes the Kling models. Then run GET /v1/models to confirm that kling-v3-motion-control appears. For list prices see the pricing page.