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

参数及使用方式已对齐官方，详细参数可直接参考官方文档。

## 一、概述

本文档说明如何通过 Kling 3.0 Turbo 原厂协议使用文生视频和图生视频能力。Turbo 与标准 Kling 3.0 采用相同的原厂协议，请求与响应结构一致，仅在能力范围、分辨率档位和计费上有所不同。

两种能力均采用异步任务模式：

1. 调用对应的创建接口。
2. 保存创建响应中的 `data.id`。
3. 使用创建任务时的同一个 API Key 查询任务状态。
4. 任务成功后，从 `outputs` 中获取并保存生成的视频。

### 1.1 接口地址

| 能力 | 创建任务 | 查询任务 |
| - | - | - |
| 文生视频 | `POST /v3/kling/text-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` |
| 图生视频 | `POST /v3/kling/image-to-video/kling-3.0-turbo` | `GET /v3/kling/tasks` |

本文示例中的完整地址为 `https://{api_domain}` 加上表中的接口路径，其中 `{api_domain}` 为您使用的 API 域名。Turbo 仅提供文生视频和图生视频，不支持 Omni 视频和动作控制。

### 1.2 鉴权

所有请求都需要携带 API Key。POST 请求还必须指定 JSON 内容类型：

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

### 1.3 响应结构

创建响应中的 `data` 为对象，常见字段为 `id`（Kling 系统生成的任务 ID，用于后续查询）、`external_id`（`options.external_task_id` 的回显，未设置时可能不返回）和 `status`（创建后的任务状态，通常为 `submitted`）。

查询响应中的 `data` 为数组，每个任务包含 `id`、`external_id`、`status`（`submitted`、`processing`、`succeeded` 或 `failed`）、`message`、`create_time`、`update_time` 和 `outputs`。`outputs` 中的视频结果常见字段为 `type`、`id`、`url`、`watermark_url` 和 `duration`，其中 `url` 是无水印结果地址，`watermark_url` 是带水印结果地址，`duration` 为视频时长（秒）。

## 二、文生视频

### 2.1 创建任务

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

请求字段：

| 字段 | 类型 | 必填 | 默认值 / 取值范围 | 说明 |
| - | - | - | - | - |
| `prompt` | string | 是 | | 文本提示词，可包含正向和负向描述；上限 3072 字符，建议不超过 2500 字符 |
| `settings.resolution` | string | 否 | 默认 `720p`；`720p`、`1080p` | 生成视频的清晰度 |
| `settings.aspect_ratio` | string | 否 | 默认 `16:9`；`16:9`、`9:16`、`1:1` | 生成视频的画面纵横比（宽:高） |
| `settings.duration` | int | 否 | 默认 5；3–15 的整数 | 生成视频时长，单位秒 |
| `options.callback_url` | string | 否 | | 任务状态变化时接收回调通知的地址 |
| `options.external_task_id` | string | 否 | | 自定义任务 ID；不覆盖系统任务 ID，可用于查询，单用户下需唯一 |
| `options.watermark_info.enabled` | boolean | 否 | 默认 `false` | 是否生成带水印结果 |

多镜头视频通过 `prompt` 的固定格式实现：“镜头 n, m, words; 镜头 n, m, words;”（半角符号分隔）。其中 n 为分镜序号（最多 6 个、最少 1 个），m 为分镜时长（每个不小于 1，所有分镜时长之和等于视频总时长），words 为分镜提示词（最长 512 字符）。

### 2.2 创建示例

```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"
    }
  }'
```

创建成功后返回任务 ID：

```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
  }
}
```

请保存 `data.id`。未传 `options.external_task_id` 时，`data.external_id` 可能不返回。

### 2.3 查询任务

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

请使用创建任务时的同一个 API Key。也可以使用 `external_task_ids` 查询自定义任务 ID。`task_ids` 和 `external_task_ids` 每次必须且只能填写一个，均支持用英文逗号分隔 1–50 个 ID，响应中的 `data` 为数组并保持请求 ID 的顺序。

### 2.4 查询示例

```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>'
```

任务成功时返回：

```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` 表示任务仍在执行，建议每隔 10–30 秒查询一次；`status=failed` 表示任务失败，不应继续轮询。任务成功后请及时保存 `outputs[type=video].url` 对应的文件，下载地址可能存在有效期。

### 2.5 计费说明

```
任务费用 = 对应分辨率的每秒单价 × settings.duration
```

价格档位仅由 `settings.resolution`（`720p` 或 `1080p`）决定。未传 `duration` 时按默认 5 秒计费。创建任务时按请求时长扣费；如果任务创建失败或最终生成失败，费用会自动退回。具体单价以您所使用服务的价格页面为准。

## 三、图生视频

### 3.1 创建任务

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

请求字段：

| 字段 | 类型 | 必填 | 默认值 / 取值范围 | 说明 |
| - | - | - | - | - |
| `contents` | array | 是 | | 参考素材合集，至少包含一项 |
| `contents[].type` | string | 是 | `prompt`、`first_frame` | 素材类型：提示词、首帧图 |
| `contents[].text` | string | 否 | | `type=prompt` 时的文本提示词，最长 2500 字符 |
| `contents[].url` | string | 否 | | `type=first_frame` 时的首帧图，支持 URL 或 Base64 |
| `settings.resolution` | string | 否 | 默认 `720p`；`720p`、`1080p` | 生成视频的清晰度 |
| `settings.duration` | int | 否 | 默认 5；3–15 的整数 | 生成视频时长，单位秒 |
| `options.external_task_id` | string | 否 | | 自定义任务 ID；不覆盖系统任务 ID，可用于查询，单用户下需唯一 |
| `options.watermark_info.enabled` | boolean | 否 | 默认 `false` | 是否生成带水印结果 |

图片支持 `.jpg`、`.jpeg` 和 `.png`，文件不超过 50 MB，宽高不小于 300 像素，宽高比在 1:2.5 到 2.5:1 之间。图生视频仅支持首帧图，暂不支持“首帧+尾帧”和“仅尾帧”。`options.callback_url` 也可传入，用法同文生视频。多镜头同样通过 `prompt` 的固定格式实现。

### 3.2 创建示例

```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"
    }
  }'
```

创建成功时返回：

```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 查询任务

使用创建响应中的 `data.id` 查询任务：

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

通过 `task_ids` 查询时，请使用创建任务时的同一个 API Key。也可以通过 `external_task_ids` 查询创建时传入的 `options.external_task_id`。查询参数支持 1–50 个英文逗号分隔的 ID。

### 3.4 查询示例

```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>'
```

任务成功时，视频地址位于 `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
        }
      ]
    }
  ]
}
```

`status=processing` 时建议每隔 10–30 秒继续查询；`status=failed` 时停止轮询并根据错误信息修正输入。

### 3.5 计费说明

```
任务费用 = 对应分辨率的每秒单价 × settings.duration
```

价格档位仅由 `settings.resolution`（`720p` 或 `1080p`）决定。未传 `duration` 时按默认 5 秒计费。创建任务时按请求时长扣费；如果任务创建失败或最终生成失败，费用会自动退回。具体单价以您所使用服务的价格页面为准。

## 四、常见错误和注意事项

接口错误采用以下结构：

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

常见状态码：400/1200（参数或内容类型不合法，按 `message` 修正）、401/1000（API Key 缺失或无效）、403/1103（无权执行）、404/1203（任务不存在或无权查询）、429/1302（请求过于频繁，降低频率并指数退避）、500/5000、503/5001、504/5002（服务异常或超时，稍后重试，避免无控制地重复提交）。若 `message` 包含 `trace_id`，联系技术支持时请一并提供。

其他注意事项：

* 请求体不需要增加 `model` 或 `model_name`，模型版本已包含在 URL 中。
* 创建任务后请持久化 `data.id`，不要把 `request_id` 当作任务 ID。
* 单次请求体最大 64 MB；较大的图片建议使用 Kling 可公开访问的公网 URL。
* 输入素材 URL 必须可被 Kling 公开访问，不能依赖内网、Cookie 或临时登录状态。
* 查询接口使用 10–30 秒轮询间隔，并设置整体超时和指数退避。
* POST 超时不代表任务一定没有创建成功；请先用 `external_task_id` 查询，再决定是否重试。
* 收到成功状态后请立即保存 `outputs[type=video].url` 对应文件，结果 URL 可能过期。

## 五、Python 调用示例

以下示例使用标准 `requests` 库，演示文生视频的创建和轮询。图生视频只需替换创建接口及请求体。

```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.