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

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

## 1. Overview

This document explains how to use text-to-video and image-to-video capabilities through the Kling 3.0 Turbo native protocol. Turbo uses the same native protocol as standard Kling 3.0, with identical request and response structures, differing only in capability scope, resolution tiers, and billing.

Both capabilities use an asynchronous task model:

1. Call the corresponding creation API.
2. Save the `data.id` from the creation response.
3. Query the task status using the same API Key that was used to create the task.
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-turbo` | `GET /v3/kling/tasks` |
| Image-to-Video | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` |

In the examples in this document, the full address is `https://{api_domain}` plus the API path in the table, where `{api_domain}` is the API domain you use. Turbo only provides text-to-video and image-to-video; it does not support Omni video or motion control.

### 1.2 Authentication

All requests require 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

The `data` in the creation response is an object. Common fields include `id` (the task ID generated by the Kling system, used for subsequent queries), `external_id` (the echo of `options.external_task_id`; may be omitted if not set), and `status` (the task status after creation, usually `submitted`).

The `data` in the query response is an array. Each task contains `id`, `external_id`, `status` (`submitted`, `processing`, `succeeded`, or `failed`), `message`, `create_time`, `update_time`, and `outputs`. Common fields for video results in `outputs` are `type`, `id`, `url`, `watermark_url`, and `duration`, where `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

### 2.1 Create Task

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

Request Fields:

| Field | Type | Required | Default / Allowed Values | Description |
| - | - | - | - | - |
| `prompt` | string | Yes | | Text prompt, can include positive and negative descriptions; up to 3072 characters, recommended no more than 2500 characters |
| `settings.resolution` | string | No | Default `720p`; `720p`, `1080p` | Resolution of the generated video |
| `settings.aspect_ratio` | string | No | Default `16:9`; `16:9`, `9:16`, `1:1` | Aspect ratio (width:height) of the generated video |
| `settings.duration` | int | No | Default 5; integer from 3 to 15 | Duration of the generated video, in seconds |
| `options.callback_url` | string | No | | URL to receive callback notifications when the task status changes |
| `options.external_task_id` | string | No | | Custom task ID; does not override the system task ID, can be used for queries, must be unique per user |
| `options.watermark_info.enabled` | boolean | No | Default `false` | Whether to generate a watermarked result |

Multi-shot video is implemented using a fixed format in `prompt`: "Shot n, m, words; Shot n, m, words;" (separated by half-width punctuation). Here, n is the shot index (1 to 6 shots), m is the shot duration (each not less than 1, and the sum of all shot durations equals the total video duration), and words is the shot prompt (up to 512 characters).

### 2.2 Create Example

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo' \
  -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",
      "aspect_ratio": "16:9",
      "duration": 5
    },
    "options": {
      "external_task_id": "turbo-text-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-turbo-text-task-id",
    "external_id": "turbo-text-20260826-0001",
    "status": "submitted",
    "create_time": 1781080778802,
    "update_time": 1781080794151
  }
}
```

Please save `data.id`. If `options.external_task_id` is not provided, `data.external_id` may not be returned.

### 2.3 Query Task

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

Use the same API Key that was used to create the task. You can also use `external_task_ids` to query custom task IDs. For each request, exactly one of `task_ids` and `external_task_ids` must be provided. Both support 1–50 IDs separated by English commas. The `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-turbo-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-turbo-text-task-id",
      "status": "succeeded",
      "outputs": [
        {
          "type": "video",
          "url": "https://your-result-cdn.example.com/turbo-text.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 and you should stop polling. After the task succeeds, save the file corresponding to `outputs[type=video].url` promptly, as the download URL may be valid for only a limited time.

### 2.5 Billing

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

The price tier is determined only by `settings.resolution` (`720p` or `1080p`). If `duration` is not provided, the default of 5 seconds is billed. Charges are applied at task creation based on the requested duration; if task creation fails or final generation fails, the fee is automatically refunded. Refer to the pricing page of the service you are using for specific unit prices.

## 3. Image-to-Video

### 3.1 Create Task

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

Request Fields:

| Field | Type | Required | Default / Allowed Values | Description |
| - | - | - | - | - |
| `contents` | array | Yes | | Collection of reference materials, must contain at least one item |
| `contents[].type` | string | Yes | `prompt`, `first_frame` | Material type: prompt, first frame image |
| `contents[].text` | string | No | | Text prompt when `type=prompt`, up to 2500 characters |
| `contents[].url` | string | No | | First frame image when `type=first_frame`, supports URL or Base64 |
| `settings.resolution` | string | No | Default `720p`; `720p`, `1080p` | Resolution of the generated video |
| `settings.duration` | int | No | Default 5; integer from 3 to 15 | Duration of the generated video, in seconds |
| `options.external_task_id` | string | No | | Custom task ID; does not override the system task ID, can be used for queries, must be unique per user |
| `options.watermark_info.enabled` | boolean | No | Default `false` | Whether to generate a watermarked result |

Images support `.jpg`, `.jpeg`, and `.png` formats. Files must not exceed 50 MB, width and height must be at least 300 pixels, and the aspect ratio must be between 1:2.5 and 2.5:1. Image-to-video only supports a first frame image; "first frame + last frame" and "last frame only" are not supported yet. `options.callback_url` can also be provided, with the same usage as in text-to-video. Multi-shot video is also implemented using the fixed format in `prompt`.

### 3.2 Create Example

```bash theme={null}
curl -X POST 'https://{api_domain}/v3/kling/image-to-video/kling-3.0-turbo' \
  -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
    },
    "options": {
      "external_task_id": "turbo-image-20260826-0001"
    }
  }'
```

On successful creation, the response is:

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

### 3.3 Query Task

Query the task using `data.id` from the creation response:

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

When querying with `task_ids`, use the same API Key that was used to create the task. You can also query using `external_task_ids` for the `options.external_task_id` passed at creation time. 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-turbo-image-task-id' \
  -H 'Authorization: Bearer <YOUR_API_KEY>'
```

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

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

When `status=processing`, it is recommended to 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 price for the corresponding resolution × settings.duration
```

The price tier is determined only by `settings.resolution` (`720p` or `1080p`). If `duration` is not provided, the default of 5 seconds is billed. Charges are applied at task creation based on the requested duration; if task creation fails or final generation fails, the fee is automatically refunded. Refer to the pricing page of the service you are using for specific unit prices.

## 4. Common Errors and Notes

API errors use the following structure:

```json theme={null}
{
  "code": 1203,
  "message": "task not found (trace_id: platform-trace-id)",
  "request_id": "",
  "data": null
}
```

Common status codes: 400/1200 (invalid parameters or content type, correct based on `message`), 401/1000 (API Key missing or invalid), 403/1103 (no permission to perform the operation), 404/1203 (task does not exist or no permission to query), 429/1302 (requests too frequent, reduce frequency and use exponential backoff), 500/5000, 503/5001, 504/5002 (service exception or timeout, retry later; avoid uncontrolled repeated submissions). If `message` contains `trace_id`, provide it when contacting technical support.

Additional notes:

* The request body does not need `model` or `model_name`; the model version is already included in the URL.
* Persist `data.id` after creating the task; do not treat `request_id` as the task ID.
* The maximum request body size is 64 MB; for larger images, it is recommended to use a publicly accessible URL for Kling.
* Input material URLs must be publicly accessible by Kling and cannot rely on intranet access, cookies, or temporary login sessions.
* Use a polling interval of 10–30 seconds for the query API, and set an overall timeout and exponential backoff.
* A POST timeout does not necessarily mean the task was not created; query first with `external_task_id` before deciding whether to retry.
* After receiving a successful status, save the file corresponding to `outputs[type=video].url` immediately, as the result URL may expire.

## 5. Python Example

The following example uses the standard `requests` library to demonstrate text-to-video creation and polling. For image-to-video, simply replace the creation API endpoint and request body.

```python theme={null}
import os
import time

import requests


api_domain = os.environ["API_DOMAIN"]
api_key = os.environ["PLATFORM_API_KEY"]
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

payload = {
    "prompt": "A calm cinematic landscape at sunrise",
    "settings": {
        "resolution": "1080p",
        "aspect_ratio": "16:9",
        "duration": 5,
    },
    "options": {
        "external_task_id": "turbo-python-20260826-0001",
    },
}

created = requests.post(
    f"https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo",
    headers=headers,
    json=payload,
    timeout=60,
)
created.raise_for_status()
task_id = created.json()["data"]["id"]

while True:
    response = requests.get(
        f"https://{api_domain}/v3/kling/tasks",
        headers={"Authorization": f"Bearer {api_key}"},
        params={"task_ids": task_id},
        timeout=30,
    )
    response.raise_for_status()
    task = response.json()["data"][0]
    if task["status"] == "succeeded":
        video = next(item for item in task["outputs"] if item["type"] == "video")
        print(video["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task)
    time.sleep(20)
```


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