# Kling/v3

Kling v3 is a video generation model family that uses the unified `kling-v3` model ID for all of the following modes:

- **Text-to-Video (`t2v`)**: provide only a prompt
- **Image-to-Video (`i2v`)**: provide a reference image as the first frame, or provide both first and last frames
- **Motion Control (`motion_control`)**: provide a reference image and a reference video to drive the character's motion

You can explicitly select the mode with `parameters.kling_v3_type`. See "Mode Selection" below.

## Mode Selection

The server determines the mode in the following order:

1. If `parameters.kling_v3_type` is provided, it takes precedence. Available values: `t2v`, `i2v`, and `motion_control`.
2. If it is not provided, the mode is inferred from the request:
   - A non-empty `input.video_url` selects `motion_control`.
   - Any first-frame image field (`parameters.image`, `input.images`, `input.first_frame_url`, or `input.img_url`) selects `i2v`.
   - Otherwise, the request uses `t2v`.

> For production use, explicitly set `kling_v3_type` to avoid routing changes if field semantics evolve.

## Submit Task (Asynchronous)

### Endpoint

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

### Input

#### Common Parameters

| Parameter                     | Type    | Required    | Description |
| :---------------------------- | :------ | :---------- | :---------- |
| model                         | string  | Yes         | Unified model name: `kling-v3` |
| parameters.kling_v3_type      | string  | No          | Explicit generation mode: `t2v`, `i2v`, or `motion_control`. If omitted, the mode is inferred from the request |
| input.prompt                  | string  | Conditional | Prompt, up to 2500 characters. Required for `t2v` and `i2v` when `multi_shot` is `false`; optional for `motion_control` |
| input.negative_prompt         | string  | No          | Negative prompt, up to 2500 characters |
| parameters.mode               | string  | No          | Generation mode. `std`: standard (720P); `pro`: professional (1080P). Default: `std` |
| parameters.aspect_ratio       | string  | No          | Aspect ratio: `16:9`, `9:16`, or `1:1`. Default: `16:9`. Ignored for `i2v`, which uses the input image's aspect ratio |
| parameters.duration           | int     | No          | Video duration in seconds. `t2v` and `i2v`: `3`–`15`; `motion_control`: `5` or `10`. Default: `5` |
| parameters.watermark_enabled  | bool    | No          | Whether to generate a watermarked result |
| parameters.external_task_id   | string  | No          | Custom task ID. It does not replace the system-generated task ID, but it can be used to query the task. Must be unique per user |

#### Text-to-Video / Image-to-Video Parameters (`t2v` / `i2v`)

| Parameter                | Type   | Required    | Description |
| :----------------------- | :----- | :---------- | :---------- |
| parameters.image         | string | Conditional | Reference image (first frame). Required for `i2v`; omit for `t2v`. Supports Base64 or a publicly accessible URL.<br>For Base64, do not include a prefix such as `data:image/png;base64,`.<br>- Supported formats: `.jpg`, `.jpeg`, `.png`<br>- Maximum size: 10 MB<br>- Minimum width and height: 300 px<br>- Aspect ratio: 1:2.5 to 2.5:1 |
| parameters.image_tail    | string | No          | Last-frame image. Must be used with `image`. Supports URL or Base64 with the same requirements as `image` |
| parameters.sound         | string | No          | Whether to generate sound. Available values: `on`, `off`. Default: `off` |
| parameters.multi_shot    | bool   | No          | Enables multi-shot mode. Default: `false`.<br>When `true`, `prompt` is ignored; when `false`, `shot_type` and `multi_prompt` are ignored |
| parameters.shot_type     | string | Conditional | Shot type. Required when `multi_shot` is `true`. Available value: `customize` |
| parameters.multi_prompt  | array  | Conditional | Multi-shot prompt list. Required when `multi_shot` is `true` and `shot_type` is `customize`.<br>- 1–6 shots<br>- Each prompt: up to 512 characters<br>- Each shot duration: at least 1 second and no longer than the total duration<br>- The sum of all shot durations must equal the total duration<br>Each item contains:<br>- `index` (int): shot number, starting from 1<br>- `prompt` (string)<br>- `duration` (string) |

#### Motion Control Parameters (`motion_control`)

| Parameter                           | Type   | Required | Description |
| :---------------------------------- | :----- | :------- | :---------- |
| input.img_url                       | string | Yes      | Reference image, provided as Base64 or a publicly accessible URL.<br>- Supported formats: `.jpg`, `.png`<br>- Maximum size: 10 MB<br>- Width and height: 300–65536 px<br>- Aspect ratio: 1:2.5 to 2.5:1 |
| input.video_url                     | string | Yes      | Reference video URL. Supports MP4 and MOV.<br>- Maximum size: 100 MB<br>- Width and height: 340–3850 px<br>- Minimum duration: 3 seconds<br>- Maximum duration: 30 seconds for landscape video and 10 seconds for portrait video |
| parameters.character_orientation    | string | Yes      | Character-facing direction. Available values: `image` (same as the reference image) or `video` (same as the reference video) |
| parameters.keep_original_sound      | string | No       | Whether to keep the reference video's original audio. Available values: `yes`, `no`. Default: `yes` |

### Request Examples

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

**Text-to-Video (`t2v`, no `image`):**

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "input": {
      "prompt": "A beautiful sunset over the ocean with waves gently crashing"
    },
    "parameters": {
      "kling_v3_type": "t2v",
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "sound": "on"
    }
  }'
```

**Image-to-Video (`i2v`, with `image` as the first frame):**

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "input": {
      "prompt": "The image comes to life with gentle movement"
    },
    "parameters": {
      "kling_v3_type": "i2v",
      "mode": "pro",
      "duration": 5,
      "image": "https://example.com/first_frame.jpg"
    }
  }'
```

**First + Last Frame Control (`i2v`):**

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "input": {
      "prompt": "A girl walking through a garden"
    },
    "parameters": {
      "kling_v3_type": "i2v",
      "mode": "pro",
      "duration": 5,
      "image": "https://example.com/first_frame.jpg",
      "image_tail": "https://example.com/last_frame.jpg"
    }
  }'
```

**Multi-shot Generation (`t2v`):**

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "kling-v3",
    "parameters": {
      "kling_v3_type": "t2v",
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "multi_shot": true,
      "shot_type": "customize",
      "multi_prompt": [
        {"index": 1, "prompt": "A person walking through a misty forest at dawn", "duration": "2"},
        {"index": 2, "prompt": "A car speeding down a rainy street, headlights glowing", "duration": "3"}
      ],
      "sound": "on"
    }
  }'
```

**Motion Control (`motion_control`, reference image + reference video):**

```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",
    "input": {
      "img_url": "https://example.com/character.jpg",
      "video_url": "https://example.com/motion_reference.mp4",
      "prompt": "A person dancing gracefully"
    },
    "parameters": {
      "kling_v3_type": "motion_control",
      "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 resources |
| 006001095  | Task response error    |
| 006001099  | Task creation error    |