> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jiekou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kling 3.0 & 3.0 Omni

Parameters and usage are aligned with the official documentation. For detailed parameters, refer directly to the official documents.

## 1. Overview

This document explains how to use text-to-video, image-to-video, Omni video, and motion control through the native Kling 3.0 protocol.

All four capabilities use asynchronous task mode:

1. Call the corresponding creation endpoint.
2. Save the `data.id` from the creation response.
3. Use the same API Key from task creation to query task status.
4. After the task succeeds, retrieve and save the generated video from `outputs`.

### 1.1 API Endpoints

| Capability | Create Task | Query Task |
| - | - | - |
| Text-to-video | `POST /v3/kling/text-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Image-to-video | `POST /v3/kling/image-to-video/kling-3.0` | `GET /v3/kling/tasks` |
| Omni video | `POST /v3/kling/omni-video/kling-3.0-omni` | `GET /v3/kling/tasks` |
| Motion control | `POST /v3/kling/motion-control/kling-3.0` | `GET /v3/kling/tasks` |

The full addresses in the examples in this document are `https://{api_domain}` plus the endpoint paths in the table, where `{api_domain}` is the API domain you use.

### 1.2 Authentication

All requests must include an API Key. POST requests must also specify the JSON content type:

```
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
```

### 1.3 Response Structure

`data` in the creation response is an object with the following common fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | Task ID generated by the Kling system, used for subsequent queries |
| `external_id` | string | Echo of `options.external_task_id`; may be omitted if not set |
| `status` | string | Task status after creation, usually `submitted` |

`data` in the query response is an array, and each task contains the following fields:

| Field | Type | Description |
| - | - | - |
| `id` | string | Task ID generated by the system |
| `external_id` | string | Custom task ID set by the caller, if any |
| `status` | string | `submitted`, `processing`, `succeeded`, or `failed` |
| `message` | string | Task status message; includes failure reason on failure, if any |
| `create_time` | integer | Creation time as Unix millisecond timestamp, if available |
| `update_time` | integer | Update time as Unix millisecond timestamp, if available |
| `outputs` | array | Generation results; a successful task usually contains one result with `type=video` |

The common fields of the video result in `outputs` are `type`, `id`, `url`, `watermark_url`, and `duration`. `url` is the non-watermarked result URL, `watermark_url` is the watermarked result URL, and `duration` is the video duration in seconds.

## 2. Text-to-Video

Official parameter documentation: Text to Video

### 2.1 Create Task

```
POST https://{api_domain}/v3/kling/text-to-video/kling-3.0
```

Common request fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `prompt` | string | Yes | Video generation prompt; cannot be empty; maximum 3072 characters |
| `settings.multi_shot` | boolean | No | Whether to generate a multi-shot video; default `true` |
| `settings.resolution` | string | No | `720p`, `1080p`, or `4k`; default `720p` |
| `settings.aspect_ratio` | string | No | `16:9`, `9:16`, or `1:1`; default `16:9` |
| `settings.audio` | string | No | `off` or `native`; default `off` |
| `settings.duration` | integer | No | 3–15 seconds; default 5 seconds |
| `options.callback_url` | string | No | Address that receives callback notifications when task status changes |
| `options.external_task_id` | string | No | Custom task ID |
| `options.watermark_info.enabled` | boolean | No | Whether to generate a watermarked result; default `false` |

When `multi_shot=true`, you can describe multiple shots in the prompt using the official Kling format; the sum of the durations of each shot should equal the total video duration.

### 2.2 Creation Example

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "A cinematic tracking shot of a red sports car driving along a coastal road at sunset",
    "settings": {
      "resolution": "1080p",
      "duration": 5,
      "audio": "native"
    },
    "options": {
      "external_task_id": "text-video-20260826-0001"
    }
  }'
```

After successful creation, the task ID is returned:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-text-task-id",
    "external_id": "text-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 2.3 Query Task

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

Save `data.id`. If `options.external_task_id` is not set, `data.external_id` may not be returned.

Use the same API Key used to create the task. If the task ID does not exist or cannot be accessed, `task not found` will be returned.

You can also use `external_task_ids` to query custom task IDs:

```
GET https://{api_domain}/v3/kling/tasks?external_task_ids={external_task_id}
```

Only one of `task_ids` and `external_task_ids` can be used per request. Both support 1–50 IDs separated by English commas. `data` in the response is an array and preserves the order of the requested IDs.

### 2.4 Query Example

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-text-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

When the task succeeds, the response is:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-text-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/text-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

`status=processing` means the task is still running; it is recommended to query every 10–30 seconds. `status=failed` means the task failed; do not continue polling. After the task succeeds, save the file corresponding to `outputs[type=video].url` promptly because the download URL may expire.

### 2.5 Billing

```
Task cost = per-second unit price for the corresponding resolution and audio tier × settings.duration
```

The price tier is determined by `settings.resolution` and `settings.audio`. For example, the cost for `1080p`, `audio=native`, `duration=5` is "per-second unit price of the 1080p native audio tier × 5 seconds". If `duration` is not provided, the cost is billed at the default 5 seconds.

The fee is deducted based on the requested duration when the task is created; if task creation fails or generation ultimately fails, the fee is automatically refunded. For the specific unit price, refer to the price page of the service you use.

## 3. Image-to-Video

Official parameter documentation: Image to Video

### 3.1 Create Task

```
POST https://{api_domain}/v3/kling/image-to-video/kling-3.0
```

Common request fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `contents` | array | Yes | Multimodal content list; at least one item |
| `contents[].type` | string | Yes | `prompt`, `first_frame`, `last_frame`, or `element` |
| `settings.resolution` | string | No | `720p`, `1080p`, or `4k`; default `720p` |
| `settings.multi_shot` | boolean | No | Whether to generate a multi-shot video; default `true` |
| `settings.audio` | string | No | `off` or `native`; default `off` |
| `settings.duration` | integer | No | 3–15 seconds; default 5 seconds |
| `options.callback_url` | string | No | Address that receives callback notifications when task status changes |
| `options.external_task_id` | string | No | Custom task ID |
| `options.watermark_info.enabled` | boolean | No | Whether to generate a watermarked result; default `false` |

`contents` sub-item fields:

| type | Required fields | Description |
| - | - | - |
| `prompt` | `text` | Text prompt; maximum 3072 characters |
| `first_frame` | `url` | First-frame image; supports URL or Base64; required |
| `last_frame` | `url` | Last-frame image; supports URL or Base64; not supported alone; a first frame must also be provided |
| `element` | `element_id`, `id` | Subject ID and the index ID used to reference the subject in the prompt; `id` must not be duplicated within the same task; up to 3 subjects can be specified |

Images support `.jpg`, `.jpeg`, and `.png`; file size must not exceed 50 MB; width and height must be at least 300 pixels; aspect ratio must be between 1:2.5 and 2.5:1.

### 3.2 Creation Example

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "type": "prompt",
        "text": "The subject turns toward the camera while the wind moves naturally through the scene"
      },
      {
        "type": "first_frame",
        "url": "https://your-cdn.example.com/first-frame.png"
      }
    ],
    "settings": {
      "resolution": "1080p",
      "duration": 5,
      "audio": "off"
    },
    "options": {
      "external_task_id": "image-video-20260826-0001"
    }
  }'
```

On successful creation, `data.id` is the task ID used for subsequent queries:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": {
    "id": "kling-image-task-id",
    "external_id": "image-video-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

### 3.3 Query Task

Use `data.id` from the creation response to query the task:

```
GET https://{api_domain}/v3/kling/tasks?task_ids={task_id}
```

When querying with `task_ids`, use the same API Key used to create the task. You can also query with `external_task_ids` using the `options.external_task_id` passed at creation. The query parameter supports 1–50 IDs separated by English commas.

### 3.4 Query Example

```bash theme={null}
curl -X GET 'https://{api_domain}/v3/kling/tasks?task_ids=kling-image-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

When the task succeeds, the video URL is in `outputs[type=video].url`:

```json theme={null}
{
  "code": 0,
  "message": "success",
  "request_id": "provider-request-id",
  "data": [
    {
      "id": "kling-image-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/image-video.mp4",
          "duration": 5
        }
      ]
    }
  ]
}
```

When `status=processing`, continue querying every 10–30 seconds; when `status=failed`, stop polling and correct the input based on the error message.

### 3.5 Billing

```
Task cost = per-second unit price for the corresponding resolution and audio tier × settings.duration
```

The price tier is determined by `settings.resolution` and `settings.audio`; if `duration` is not provided, the cost is billed at the default 5 seconds. The fee is deducted based on the requested duration when the task is created; if task creation fails or generation ultimately fails, the fee is automatically refunded. For the specific unit price, refer to the price page of the service you use.

## 4. Omni Video

Official parameter documentation: Omni Video

### 4.1 Create Task

```
POST https://{api_domain}/v3/kling/omni-video/kling-3.0-omni
```

Common request fields:

| Field | Type | Required | Description |
| - | - | - | - |
| `contents` | array | Yes | Multimodal content list; at least one item |
| `contents[].type` | string | Yes | `prompt`, `first_frame`, `last_frame`, `refer_image`, `feature_video`, `base_video`, or `element` |
| `settings.resolution` | string | No | `720p`, `1080p`, or `4k`; default `720p` |
| `settings.multi_shot` | boolean | No | Whether to generate a multi-shot video; default `true` |
| `settings.aspect_ratio` | string | No | `16:9`, `9:16`, or `1:1`; default `16:9`; required when there is no first-frame image or no reference video |
| `settings.audio` | string | No | `off`, `native`, or `original`; default `off` |
| `settings.duration` | integer | No | 3–15 seconds; default 5 seconds |
| `options.callback_url` | string | No | Address that receives callback notifications when task status changes |
| `options.external_task_id` | string | No | Custom task ID |
| `options.watermark_info.enabled` | boolean | No | Whether to generate a watermarked result; default `false` |

`contents` sub-item fields:

| type | Required fields | Description |
| - | - | - |
| `prompt` | `text` | Text prompt; maximum 3072 characters |
| `first_frame`, `last_frame`, `refer_image` | `url`; `id` optional | Image assets; supports URL or Base64; `id` is used to reference the asset in the prompt and must not be duplicated within the same task |
| `feature_video`, `base_video` | `url`; `id` optional | Video assets; supports URL; `id` is used to reference the asset in the prompt and must not be duplicated within the same task |
| `element` | `element_id`, `id` | Subject ID and the index ID used to reference the subject in the prompt; `id` must not be duplicated within the same task |

Images support `.jpg`, `.jpeg`, and `.png`; file size must not exceed 50 MB; width and height must be at least 300 pixels; aspect ratio must be between 1:2.5 and 2.5:1. Videos support `.mp4` and `.mov`; file size must not exceed 200 MB; duration must be 3–15.5 seconds.

Audio combination rules:

* `feature_video` (feature reference video): `audio` can only be `off` (original video audio is not supported), and `multi_shot` can only be `true`.
* `base_video` (video to edit): `audio` cannot be `native` (can be `off` or `original`), and multi-shot is not supported. `audio=original` is only available for requests that include a reference video.
* When no video input is included, `audio=off` or `audio=native` can be used.

### 4.2 Creation Example

The following example uses a reference image to generate a video:

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/omni-video/kling-3.0-omni' \
  -H 'Authorization: Bearer <YOUR_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [
      {
        "type": "prompt",
        "text": "Keep the character consistent and create a cinematic walking shot"
      },
      {
        "type": "refer_image",
        "url": "https://your-cdn.example.com/character.png"
      }
    ],
    "settings": {
      "resolution": "1080p",
      "duration": 8,
      "audio": "native
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.