Kling 3.0 Turbo

curl --request POST \
  --url https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo

const options = {method: 'POST'};

fetch('https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

POST

kling

text-to-video

kling-3.0-turbo

Kling 3.0 Turbo

curl --request POST \
  --url https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo

const options = {method: 'POST'};

fetch('https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo"

	req, _ := http.NewRequest("POST", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://{api_domain}/v3/kling/text-to-video/kling-3.0-turbo")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)

response = http.request(request)
puts response.read_body

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

一、概述

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

调用对应的创建接口。
保存创建响应中的 data.id。
使用创建任务时的同一个 API Key 查询任务状态。
任务成功后，从 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 创建示例

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：

{
  "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 查询示例

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

任务成功时返回：

{
  "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 创建示例

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

创建成功时返回：

{
  "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 查询示例

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：

{
  "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

四、常见错误和注意事项

接口错误采用以下结构：

{
  "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 库，演示文生视频的创建和轮询。图生视频只需替换创建接口及请求体。

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)

最后修改于 2026年10月15日

API 基础

API Key 管理

大语言

图像

视频

音频

Kling 3.0 Turbo

一、概述

1.1 接口地址

1.2 鉴权

1.3 响应结构

二、文生视频

2.1 创建任务

2.2 创建示例

2.3 查询任务

2.4 查询示例

2.5 计费说明

三、图生视频

3.1 创建任务

3.2 创建示例

3.3 查询任务

3.4 查询示例

3.5 计费说明

四、常见错误和注意事项

五、Python 调用示例

​一、概述

​1.1 接口地址

​1.2 鉴权

​1.3 响应结构

​二、文生视频

​2.1 创建任务

​2.2 创建示例

​2.3 查询任务

​2.4 查询示例

​2.5 计费说明

​三、图生视频

​3.1 创建任务

​3.2 创建示例

​3.3 查询任务

​3.4 查询示例

​3.5 计费说明

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

​五、Python 调用示例

一、概述

1.1 接口地址

1.2 鉴权

1.3 响应结构

二、文生视频

2.1 创建任务

2.2 创建示例

2.3 查询任务

2.4 查询示例

2.5 计费说明

三、图生视频

3.1 创建任务

3.2 创建示例

3.3 查询任务

3.4 查询示例

3.5 计费说明

四、常见错误和注意事项

五、Python 调用示例