# Kling/V3-Omni

Multimodal Video Generation Model supporting text, image, and video as multimodal inputs.

## 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-omni` |
| input.prompt                      | string  | No       | Prompt, up to 2500 characters. Must not be empty when `multi_shot` is false.<br>You can reference images/videos using `<<<image_1>>>`, `<<<video_1>>>` |
| input.negative_prompt             | string  | No       | Negative prompt, up to 2500 characters. Recommended to include negation directly in the main prompt |
| parameters.mode                   | string  | No       | Generation mode. `std`: standard mode (720P); `pro`: professional mode (1080P). Default is `pro` |
| parameters.aspect_ratio           | string  | Conditional | Video aspect ratio. Options: `16:9`, `9:16`, `1:1`. Can be omitted only when using video editing (`refer_type: base`) |
| parameters.duration               | int     | No       | Video duration (seconds), range: `3` ~ `15`, default `5`.<br>When using video reference, only `3` ~ `10` seconds are supported.<br>When using video editing (`refer_type: base`), output duration matches input video and this parameter is ignored |
| parameters.sound                  | string  | No       | Whether to generate sound. Options: `on`, `off`, default `off`.<br>Must be `off` when using video reference |
| parameters.multi_shot             | bool    | No       | Whether to enable multi-shot mode. Default is `false`.<br>When `true`, `prompt` is ignored; when `false`, `shot_type` and `multi_prompt` are ignored |
| parameters.shot_type              | string  | No       | Shot type. Required when `multi_shot` is `true`. Available value: `customize` |
| parameters.multi_prompt           | array   | No       | Multi-shot prompt list. Required when `multi_shot` is `true` and `shot_type` is `customize`.<br>- Min 1 shot, max 6 shots<br>- Each prompt ≤ 512 characters<br>- Each shot duration ≥1s and ≤ total duration<br>- Sum of all shot durations must equal total duration<br>Each item includes:<br>- `index`: shot index starting from 1 (int)<br>- `prompt`: shot prompt (string)<br>- `duration`: shot duration (string) |
| parameters.image_list             | array   | No       | Reference image list. Supports first frame / end frame / reference images. Each item includes:<br>- `image_url`: image URL or Base64 (required)<br>- `type`: `first_frame` or `end_frame` (optional)<br><br>Constraints:<br>- With video reference: ≤4 images<br>- Without video reference: ≤7 images<br>- When image count >2, end frame is not supported<br>- End frame cannot be used alone (must include first frame) |
| parameters.video_list             | array   | No       | Reference video list, max 1 video. Each item includes:<br>- `video_url`: video URL (required, supports MP4/MOV)<br>- `refer_type`: `feature` (reference) or `base` (edit), default `base`<br>- `keep_original_sound`: `yes` or `no`<br><br>Constraints:<br>- Video length must be 3–10 seconds<br>- Cannot define first/end frame when editing video<br>- `sound` must be `off` when using video reference |
| parameters.watermark_enabled      | bool    | No       | Whether to generate watermarked output. Custom watermark is not supported |
| parameters.external_task_id       | string  | No       | Custom task ID. Does not override system task ID, but can be used for querying. Must be unique per user |

**Image Requirements**:
- Supported formats: `.jpg`, `.jpeg`, `.png`
- File size: ≤10MB
- Dimensions: minimum 300px, aspect ratio between 1:2.5 and 2.5:1
- When using Base64, do NOT include prefixes like `data:image/png;base64,`

**Video Requirements**:
- Supported formats: MP4, MOV
- Minimum duration: 3 seconds
- Resolution: 720px ~ 2160px
- Frame rate: 24fps ~ 60fps (output is 24fps)
- Max 1 video, size ≤200MB

### Request Examples

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

**Text-to-Video:**

```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-omni",
    "input": {
      "prompt": "A beautiful sunset over the ocean with waves gently crashing"
    },
    "parameters": {
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "sound": "on"
    }
  }'
```

**Image Reference + First/Last 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-omni",
    "input": {
      "prompt": "A girl walking through a garden"
    },
    "parameters": {
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "image_list": [
        {"image_url": "https://example.com/first_frame.jpg", "type": "first_frame"},
        {"image_url": "https://example.com/last_frame.jpg", "type": "end_frame"}
      ]
    }
  }'
```

**Video Editing (Base Video):**

```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-omni",
    "input": {
      "prompt": "Add a cinematic color grading effect"
    },
    "parameters": {
      "mode": "pro",
      "video_list": [
        {
          "video_url": "https://example.com/input.mp4",
          "refer_type": "base",
          "keep_original_sound": "yes"
        }
      ]
    }
  }'
```

**Multi-shot + Image Reference:**

```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-omni",
    "parameters": {
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": 5,
      "multi_shot": true,
      "shot_type": "customize",
      "multi_prompt": [
        {"index": 1, "prompt": "<<<image_1>>>A person sitting on a park bench, sunlight filtering through trees", "duration": "2"},
        {"index": 2, "prompt": "A car speeding down a rainy street, headlights glowing", "duration": "3"}
      ],
      "image_list": [
        {"image_url": "https://example.com/person.jpg"}
      ],
      "sound": "on"
    }
  }'
```

### 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         |