---
title: "Kling AI Motion Control API Reference"
aliases: [kling-motion-control, motion-control-api]
tags: [kling, video-generation, api, motion-control, pose-transfer]
sources: [raw/Kling AI Next-Gen AI Video & AI Image Generator 4.md]
created: 2026-04-26
updated: 2026-04-26
---

## Overview

Motion Control (`/v1/videos/motion-control`) drives a character in a **reference image** using the motion captured from a **reference video** — essentially pose/motion transfer. The generated video length matches the reference video duration.

Supported models: `kling-v2-6`, `kling-v3`

Base URL: `https://api-singapore.klingai.com`

---

## Create Task

**POST** `/v1/videos/motion-control`

### Required Fields

| Field | Type | Notes |
|-------|------|-------|
| `model_name` | enum | `kling-v2-6` or `kling-v3` |
| `image_url` | string | Reference character image (Base64 raw or URL) |
| `video_url` | string | Reference motion video (mp4/mov) |
| `character_orientation` | enum | `image` or `video` |
| `mode` | enum | `std` (cost-effective) or `pro` (high quality) |

### Optional Fields

| Field | Type | Notes |
|-------|------|-------|
| `prompt` | string | Max 2500 chars; add scene elements, camera hints |
| `keep_original_sound` | enum | `yes` / `no` |
| `element_list` | array | One element ID from element library |
| `watermark_info` | object | `{ "enabled": boolean }` |
| `callback_url` | string | Webhook for status change notifications |
| `external_task_id` | string | Your own task ID (unique per account) |

### Minimal Example

```bash
curl --request POST \
  --url https://api-singapore.klingai.com/v1/videos/motion-control \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data-raw '{
    "model_name": "kling-v2-6",
    "image_url": "https://example.com/character.png",
    "video_url": "https://example.com/dance.mp4",
    "character_orientation": "image",
    "mode": "pro",
    "keep_original_sound": "yes"
  }'
```

### Response

```json
{
  "code": 0,
  "request_id": "string",
  "data": {
    "task_id": "string",
    "task_status": "submitted",
    "created_at": 1722769557708,
    "updated_at": 1722769557708
  }
}
```

Task statuses: `submitted` → `processing` → `succeed` / `failed`

---

## Query Task (Single)

**GET** `/v1/videos/motion-control/{task_id}`

- Can query by system `task_id` **or** your `external_task_id` in the path

```bash
curl --request GET \
  --url https://api-singapore.klingai.com/v1/videos/motion-control/{task_id} \
  --header 'Authorization: Bearer <token>'
```

### Result Shape

```json
{
  "data": {
    "task_id": "string",
    "task_status": "succeed",
    "task_result": {
      "videos": [
        {
          "id": "string",
          "url": "string",          // anti-leech, expires 30 days
          "watermark_url": "string",
          "duration": "string"      // seconds
        }
      ]
    },
    "final_unit_deduction": "string"
  }
}
```

---

## Query Task (List)

**GET** `/v1/videos/motion-control?pageNum=1&pageSize=30`

- `pageNum`: 1–1000
- `pageSize`: 1–500

Returns same per-task structure as single query, wrapped in a data array.

---

## Constraints & Tips

### Image Requirements (`image_url`)
- Formats: `.jpg` / `.jpeg` / `.png`
- Size: ≤ 10 MB; dimensions: 300 px – 65536 px; aspect ratio: 1:2.5 – 2.5:1
- Character should be full-body or clear upper body, no occlusion
- **Base64**: submit raw string only — no `data:image/png;base64,` prefix

### Video Requirements (`video_url`)
- Formats: `.mp4` / `.mov`; size: ≤ 100 MB; dimensions: 340 px – 3850 px
- Duration: min 3 s; max depends on `character_orientation`:
  - `image` → max **10 s**
  - `video` → max **30 s**
- Single continuous shot — no cuts, no camera movement
- Single person preferred; 2+ people → largest on-screen person is used
- Output length = reference video duration (may be shorter for fast/complex actions; credits not refunded)

### `character_orientation` Modes
| Value | Orientation follows | Max video duration |
|-------|--------------------|--------------------|
| `image` | Character pose in the reference image | 10 s |
| `video` | Character pose in the reference video | 30 s |

### Generation Modes
| Value | Description |
|-------|-------------|
| `std` | Standard — cost-effective |
| `pro` | Professional — higher quality |

---

## Key Takeaways

- Motion Control = **pose/motion transfer**: character from image moves like the actor in the reference video
- Output duration matches reference video; minimum extractable motion is 3 s
- Videos **expire after 30 days** — download and store immediately
- Use `character_orientation: "image"` for short clips (≤10 s), `"video"` for up to 30 s
- Base64 images must be raw — no `data:` prefix or the request will fail
- Single-person, full-body, stable reference videos yield the best results
- Errors surface in `task_status_msg` when status is `failed`

---

## Related

- [[wiki/web-agency/kling-text-to-video-api|Kling Text-to-Video API]] — generate video from prompt only
- [[wiki/web-agency/kling-image-to-video-api|Kling Image-to-Video API]] — animate a still or interpolate two frames
- [[wiki/web-agency/kling-multi-image-to-video-api|Kling Multi-Image-to-Video API]] — composite 2–4 reference images
- [[wiki/web-agency/claude-code-nanobanana-website-workflow|Claude Code + Nanobanana 2 Workflow]] — end-to-end agency workflow using Kling

---

## Sources

- Raw article: `raw/Kling AI Next-Gen AI Video & AI Image Generator 4.md`
- Origin: https://kling.ai/document-api/apiReference/model/motionControl
