# Kling/v3-Motion-Control

Motion-Control Video Generation Model. Generates videos with specified motion control based on a reference image and a reference video.

## Submit Task (Asynchronous)

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/submit`

### Input

| Parameter                        | Type   | Required | Description |
| :------------------------------- | :----- | :------- | :---------- |
| model                            | string | Yes      | Model name, here it is `kling-v3-motion-control` |
| input.img_url                    | string | Yes      | Reference image. Supports Base64-encoded image or image URL (must be accessible).<br>- Supported formats: `.jpg`, `.png`<br>- File size must not exceed 10MB<br>- Width and height must be between 300px and 65536px<br>- Aspect ratio must be between 1:2.5 and 2.5:1 |
| input.video_url                  | string | Yes      | Reference video URL. Supports MP4 and MOV formats.<br>- File size must not exceed 100MB<br>- Width and height must be between 340px and 3850px<br>- Video duration must be at least 3 seconds; landscape videos must not exceed 30 seconds, and portrait videos must not exceed 10 seconds |
| parameters.character_orientation | string | Yes      | Character orientation, which determines the facing direction of the character. Available values: `image` (same orientation as the reference image), `video` (same orientation as the reference video) |
| parameters.mode                  | string | Yes      | Generation mode. `std`: standard mode; `pro`: professional mode (high quality) |
| input.prompt                     | string | No       | Prompt, up to 2500 characters |
| parameters.duration              | int    | No       | Video duration (seconds). Available values: `5`, `10`. Default is `5` |
| parameters.aspect_ratio          | string | No       | Video aspect ratio. Available values: `16:9`, `9:16`, `1:1`. Default is `16:9` |
| parameters.keep_original_sound   | string | No       | Whether to retain the original sound from the reference video. Available values: `yes`, `no`. Default is `yes` |
| parameters.watermark_enabled     | bool   | No       | Whether to generate a watermarked result |
| parameters.external_task_id      | string | No       | Custom task ID. It does not override the system-generated task ID, but it can be used to query the task. Please ensure it is unique per user |

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or other API tools.

```shell
curl -X POST 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
-H 'Authorization: <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
    "model": "kling-v3-motion-control",
    "input": {
      "img_url": "https://example.com/character.jpg",
      "video_url": "https://example.com/motion_reference.mp4",
      "prompt": "A person dancing gracefully"
    },
    "parameters": {
      "duration": 5,
      "aspect_ratio": "16:9",
      "character_orientation": "image",
      "mode": "std"
    }
  }'
```

### Output

| Parameter      | Type   | Description                         |
| :------------- | :----- | :---------------------------------- |
| output.task_id | string | Unique identifier of the async task |
| request_id     | string | Unique identifier of the request    |

### Response Example

```json
{
  "output": {
    "task_id": "task_id"
  },
  "request_id": "request_id"
}
```

## Query Task Status

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>`

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>' \
--header 'Authorization: <YOUR_API_KEY>'
```

### Output

| Parameter            | Type    | Description                                             |
| :------------------- | :------ | :------------------------------------------------------ |
| output.task_id       | string  | Unique identifier of the async task                     |
| output.task_status   | string  | Task status: `Pending`, `Running`, `Success`, `Failure` |
| output.urls          | array   | List of video result URLs                               |
| output.submit_time   | integer | Task submission timestamp                               |
| output.finish_time   | integer | Task completion timestamp                               |
| output.error_message | string  | Error message returned when failed                      |
| usage.duration       | integer | Video duration (seconds)                                |
| request_id           | string  | Unique identifier of the request                        |

### Response Example (Success)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Success",
    "urls": ["https://xxxxx/xxxx.mp4"],
    "submit_time": 1756959000,
    "finish_time": 1756959050
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}
```

### Response Example (Failure)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Failure",
    "submit_time": 1756959000,
    "finish_time": 1756959019,
    "error_message": "error_message"
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}
```

## Error Codes

| Error Code | Description                 |
| :--------- | :-------------------------- |
| 006001094  | Insufficient task resources |
| 006001095  | Task response error         |
| 006001099  | Task creation error         |