---
title: "Kling AI: Next-Gen AI Video & AI Image Generator"
source: "https://kling.ai/document-api/apiReference/model/motionControl"
author:
published:
created: 2026-04-24
description:
tags:
  - "clippings"
---
## Create Task

POST `/v1/videos/motion-control`

```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://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/multi-3.ng.png",
    "prompt": "The girl is wearing a loose gray T-shirt and denim shorts",
    "video_url": "https://p2-kling.klingai.com/kcdn/cdn-kcdn112452/kling-qa-test/dance.mp4",
    "keep_original_sound": "yes",
    "character_orientation": "image",
    "mode": "pro",
    "callback_url": "",
    "external_task_id": "xxx"
  }'
```

200

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_info": { //Task creation parameters
      "external_task_id": "string" //Customer-defined task ID
    },
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Request Body

Model Name

Enum values：kling-v2-6kling-v3

promptstringOptional

Text prompt, can include positive and negative descriptions

- Can add elements to the scene, achieve camera movement effects, etc. See [Kling "Motion Control" User Guide](https://kling.ai/quickstart/motion-control-user-guide)

- Cannot exceed 2500 characters

image\_urlstringRequired

Reference image. Characters, background and other elements in generated video will follow this reference.

- Video content requirements:
	- Character proportions should match the reference motion as much as possible; avoid driving half-body characters with full-body motions
		- Character should show clear upper body or full body including limbs and head, avoid occlusion
		- Avoid extreme orientations (upside down, lying flat, etc.). Character should occupy sufficient screen area
		- Supports realistic/stylized characters (including humans/humanoid animals/some pure animals/some humanoid body proportion characters)

- Supports image Base64 encoding or image URL (ensure accessibility)

- Important: When using Base64, do NOT add any prefix like `data:image/png;base64,`. Submit only the raw Base64 string.

- Correct Base64 format:

```
iVBORw0KGgoAAAANSUhEUgAAAAUA...
```

- Incorrect Base64 format (with data: prefix):

```
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...
```

- Supported image formats:.jpg /.jpeg /.png

- File size: ≤10MB, dimensions: 300px ~ 65536px, aspect ratio: 1:2.5 ~ 2.5:1

video\_urlstringRequired

URL of reference video. Character actions in generated video will follow this reference.

- Video content requirements:
	- Character should show clear upper body or full body including all limbs and head, avoid occlusion
		- Recommend uploading single-person action video; for 2+ people, actions will be taken from the character with largest screen proportion
		- Recommend using real person actions; some stylized characters/humanoid body proportions may work
		- Video should be single continuous shot with character always visible, avoid cuts or camera movements (will be truncated otherwise)
		- Avoid overly fast actions; relatively stable actions produce better results

- Supported formats:.mp4 /.mov, file size: ≤100MB, dimensions: 340px ~ 3850px. Validation failures will return error codes.

- Duration limits: minimum 3 seconds, maximum depends on character\_orientation:
	- When character\_orientation is "video": maximum 30 seconds
		- When character\_orientation is "image": maximum 10 seconds

- The duration range of the uploaded motion reference is from 3 to 30 seconds, in which the generated video length will align with the duration of the uploaded video. If motions are complex or fast-paced, there is a chance that the output may be shorter than the uploaded video duration, as the model can only extract the valid action duration for generation. The minimum extractable continuous action duration is 3 seconds. Please note that in such cases, the consumed credits cannot be refunded. It is recommended to adjust the complexity and speed of the actions accordingly.

- System will validate video content and return error codes if issues are found

element\_listarrayOptional

Reference Element List based on element ID configuration

- Load with key:value format as follows:

```json
"element_list":[
  { "element_id": 829836802793406551 }
]
```

- When referencing the element, the generated video can only temporarily refer to the orientation of the person in the video.

- Currently, only one element can be introduced.

▾Hide child attributes

element\_idlongRequired

Element ID from element library

Whether to keep the original sound of the video

Enum values：yesno

character\_orientationstringRequired

Character orientation in generated video, can match image or video

Enum values：imagevideo

- image: Match character orientation in the image; reference video duration must not exceed 10 seconds

- video: Match character orientation in the video; reference video duration must not exceed 30 seconds

- When referencing the element, the generated video can only temporarily refer to the orientation of the person in the video.

modestringRequired

Video generation mode

Enum values：stdpro

- std: Standard Mode - basic mode, cost-effective

- pro: Professional Mode (High Quality) - high performance mode, better video quality

Support varies by model version and video mode. See [Capability Map](https://kling.ai/document-api/apiReference/model/videoModels) for details.

watermark\_infoobjectOptional

Whether to generate watermarked results simultaneously

- Defined by the enabled parameter, format:

```json
"watermark_info": { "enabled": boolean }
```

- true: generate watermarked result, false: do not generate

- Custom watermarks are not currently supported

callback\_urlstringOptional

Callback notification URL for task result. If configured, server will notify when task status changes.

- For specific message schema, see [Callback Protocol](https://kling.ai/document-api/apiReference/callbackProtocol)

external\_task\_idstringOptional

Customized Task ID

- Will not overwrite system-generated task ID, but supports querying task by this ID

- Must be unique within a single user account

---

## Query Task (Single)

GET `/v1/videos/motion-control/{id}`

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

200

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems
  "data": {
    "task_id": "string", // Task ID, generated by the system
    "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
    "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
    "task_info": { //Task creation parameters
      "external_task_id": "string" //Customer-defined task ID
    },
    "task_result": {
      "videos": [
        {
          "id": "string", // Generated video ID; globally unique
          "url": "string", // URL for generating videos, anti-leech format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
          "watermark_url": "string", // Watermarked video download URL, anti-leech format
          "duration": "string" //Total video duration, unit: s (seconds)
        }
      ]
    },
    "watermark_info": {
      "enabled": boolean
       },
    "final_unit_deduction": "string", // The deduction units of task
    "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
    "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
  }
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Path Parameters

task\_idstringOptional

Task ID for Motion Control. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying.

external\_task\_idstringOptional

Customized Task ID for Motion Control. Fill the value directly in the request path. Choose either task\_id or external\_task\_id for querying.

---

## Query Task (List)

GET `/v1/videos/motion-control`

```bash
curl --request GET \
  --url 'https://api-singapore.klingai.com/v1/videos/motion-control?pageNum=1&pageSize=30' \
  --header 'Authorization: Bearer <token>'
```

200

```json
{
  "code": 0, // Error codes; Specific definitions can be found in "Error Code"
  "message": "string", // Error information
  "request_id": "string", // Request ID, generated by the system, used to track requests and troubleshoot problems
  "data": [
    {
      "task_id": "string", // Task ID, generated by the system
      "task_status": "string", // Task status, Enum values: submitted, processing, succeed, failed
      "task_status_msg": "string", // Task status information, displaying the failure reason when the task fails (such as triggering the content risk control of the platform, etc.)
      "task_info": { //Task creation parameters
        "external_task_id": "string" //Customer-defined task ID
      },
      "task_result": {
        "videos": [
          {
            "id": "string", // Generated video ID; globally unique
            "url": "string", // URL for generating videos, anti-leech format (To ensure information security, generated images/videos will be cleared after 30 days. Please make sure to save them promptly.)
            "watermark_url": "string", // Watermarked video download URL, anti-leech format
            "duration": "string" //Total video duration, unit: s (seconds)
          }
        ]
      },
      "watermark_info": {
        "enabled": boolean
      },
      "final_unit_deduction": "string", // The deduction units of task
      "created_at": 1722769557708, // Task creation time, Unix timestamp, unit: ms
      "updated_at": 1722769557708 //Task update time, Unix timestamp, unit: ms
    }
  ]
}
```

### Request Header

Data Exchange Format

AuthorizationstringRequired

Authentication information, refer to API authentication

### Query Parameters

Page number

- Value range: \[1, 1000\]

Data volume per page

- Value range: \[1, 500\]