大模型服务平台 TokenHub Kling 调用指南

概述
可灵（Kling）是快手推出的视频生成模型系列，支持文生视频、图生视频、全能视频生成（Omni）等能力，并配套元素管理（自定义主体）接口。
本文介绍如何通过 TokenHub 调用可灵的六款模型：kling-video-v2.5-turbo、kling-video-v2.6、kling-video-v3-turbo、kling-video-v3、kling-video-v3-omni、kling-video-o1。
前提条件
已 注册腾讯云 账号并开通 TokenHub 服务。
已在 TokenHub 控制台 获取 API Key。
说明：
下文所有示例中的 YOUR_API_KEY 均需替换为您自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。
调用流程
视频生成为耗时任务，接口采用异步调用模式，统一分两步：
1. 提交任务：调用生成接口（文生/图生/全能），成功返回 data.id（任务 ID）。
2. 轮询结果：携带任务 ID 调用 查询任务结果 接口，直至 data.status = succeeded，从结果中获取视频地址。
注意：
通用响应制式：code（0 表示成功）、message（提示信息）、request_id（请求 ID，用于问题排查）、data（数据对象）。任务状态统一为：submitted（已提交）/ processing（处理中）/ succeeded（成功）/ failed（失败）。
模型列表
模型名称
model 参数值
支持能力
视频时长（秒）
清晰度档位
画面宽高比（文生/全能）
选型建议
Kling-Video-V3
kling-video-v3
文生 / 图生（含首尾帧、元素）
3 ~ 15
720p / 1080p / 4k
16:9、9:16、1:1
旗舰款：支持原生音频、多镜头、元素引用与 4K，能力最全
Kling-Video-V3-omni
kling-video-v3-omni
全能视频生成（文/图/视频多模态输入、视频编辑）
3 ~ 15
720p / 1080p / 4k
16:9、9:16、1:1
需要参考视频、视频编辑等多模态混合输入场景
Kling-Video-V3-turbo
kling-video-v3-turbo
文生 / 图生
3 ~ 15
720p / 1080p
16:9、9:16、1:1
V3 快速版，生成更快、成本更低，适合批量生成；参数精简（无音频、多镜头）
Kling-Video-O1
kling-video-o1
全能视频生成（多模态统一入口）
3 ~ 10
720p / 1080p
16:9、9:16、1:1
O1 系列多模态统一生成入口
Kling-Video-V2.6
kling-video-v2.6
文生 / 图生（含首尾帧）
5 / 10
720p / 1080p
16:9、9:16、1:1
支持原生音频的成熟方案
Kling-Video-V2.5-turbo
kling-video-v2.5-turbo
文生 / 图生（含首尾帧）
5 / 10
720p / 1080p
16:9、9:16、1:1
参数最精简的入门款，成本敏感场景
说明：
「画面宽高比」列为文生视频、全能视频生成支持的取值范围；图生视频、首尾帧生视频无 aspect_ratio 参数，输出画幅跟随输入图片比例。
文生视频
1. 接口描述
仅凭文本提示词生成视频。V3 支持多镜头模板语法，详情请参见 附录：多镜头提示词语法、原生音频与 4K 输出。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/text-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v2.5-turbo、kling-video-v2.6、kling-video-v3-turbo、kling-video-v3
prompt
是
string
提示词，可包含正向与负向描述。V3：≤ 3072 字符（建议 ≤ 2500），支持多镜头模板语法；V3 Turbo / V2.6 / V2.5 Turbo：≤ 2500 字符。
settings
否
object
输出配置，子字段见下表（各模型支持的字段不同）。
settings 子字段（按模型）：
子字段
适用模型
描述
resolution
全部
清晰度。V3：720p / 1080p / 4k；其余：720p / 1080p。默认值：720p。
aspect_ratio
全部
画面宽高比。枚举：16:9 / 9:16 / 1:1。默认值：16:9。
duration
全部
时长（秒）。V3 / V3 Turbo：3~15 整数；V2.6 / V2.5 Turbo：5 / 10。默认值：5。
multi_shot
仅 V3
是否生成多镜头视频，默认 true；设为 false 时多镜头提示词不产生多镜头输出。
audio
仅 V3 / V2.6
音频。枚举：native（生成与画面匹配的原生音频）/ off（默认）。注意：V2.6 文生视频在 audio=native 时仅支持 1080p。
说明：
kling-video-v3-turbo、kling-video-v2.5-turbo 的 settings 仅支持 resolution / aspect_ratio / duration 三个字段，不支持 multi_shot 与 audio。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/text-to-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-v3",
  "prompt": "A girl sat on the train, looking out the window, sunlight streaming across her face",
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "audio": "native"
  }
}'
说明：
将示例中的 model 替换为 kling-video-v3-turbo、kling-video-v2.6 或 kling-video-v2.5-turbo，即可调用对应模型（注意各模型 settings 字段差异，V3 Turbo 与 V2.5 Turbo 不支持 audio / multi_shot）。
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功，其它值见 附录：统一错误码。
message
string
错误或提示信息；成功时通常为 "success" 或空字符串。
request_id
string
请求 ID，由系统生成，用于问题追踪与排查。
data
object
任务数据对象。
data.id
string
系统生成的任务 ID，用于后续任务查询。
data.status
string
任务状态：submitted / processing / succeeded / failed。
data.create_time
long
任务创建时间；Unix 时间戳，单位毫秒。
data.update_time
long
任务更新时间；Unix 时间戳，单位毫秒。
data.external_id
string
自定义任务 ID（请求中传入了 external_task_id 时回显）。
5. 响应示例
{
  "code": 0,
  "message": "success",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务提交成功后，生成阶段的任务状态通过 查询任务结果 接口获取：
status
含义
处理建议
submitted
已提交
继续轮询。
processing
处理中
继续轮询。
succeeded
生成成功
从查询结果中获取视频地址。
failed
生成失败
查看失败原因，修改后重试；持续失败请联系技术支持并附 request_id。
图生视频
1. 接口描述
以图片为首帧（V3 / V2.6 / V2.5 Turbo 可选尾帧）结合文本提示词生成视频。V3 额外支持元素引用（Element）。图片直接传入公网 URL 或 Base64，输出画幅跟随输入图片。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/image-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v2.5-turbo、kling-video-v2.6、kling-video-v3-turbo、kling-video-v3
contents
是
array
参考素材集合，同一素材的字段放在同一对象内；至少包含一个 prompt 与一个 first_frame。子字段见下表。
settings
否
object
输出配置，子字段见下表。注意：图生视频无 aspect_ratio 参数，画幅由输入图片决定。
options
否
object
通用配置，同「文生视频」。
contents 数组元素子字段：
参数名
必选
类型
描述
type
是
string
素材类型。各模型支持：V3：prompt / first_frame / last_frame / element；V2.6：prompt / first_frame / last_frame；V3 Turbo：prompt / first_frame；V2.5 Turbo：prompt / first_frame / last_frame。
text
条件必选
string
文本提示词，type=prompt 时必选。≤ 2500 字符；V3 支持多镜头模板语法与 @元素 引用。
url
条件必选
string
图片素材（URL 或 Base64），type=first_frame / last_frame 时必选。约束：.jpg/.jpeg/.png，≤ 50MB，宽高均 ≥ 300px，宽高比 1:2.5 ~ 2.5:1。
element_id
条件必选
string
元素引用（JSON 定义），type=element 时必选，仅 V3；最多 3 个，在 prompt 中以 @xxx 引用。
settings 子字段（按模型）：
子字段
适用模型
描述
resolution
全部
清晰度。V3：720p / 1080p / 4k；其余：720p / 1080p。默认值：720p。注意：V2.6 使用首尾帧生成时仅支持 720p、audio=native 时仅支持 1080p；V2.5 Turbo 使用首尾帧生成时仅支持 1080p。
duration
全部
时长（秒）。V3 / V3 Turbo：3~15 整数；V2.6 / V2.5 Turbo：5 / 10。默认值：5。
multi_shot
仅 V3
是否生成多镜头视频，默认 true。
audio
仅 V3 / V2.6
音频。枚举：native / off（默认 off）。注意：V2.6 图生视频在 audio=native 时仅支持 1080p。
注意：
首尾帧仅支持「仅首帧」和「首帧+尾帧」，不支持仅尾帧。
元素名避免互为子串（如 @Zhang 与 @ZhangSan）。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/image-to-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-v3",
  "contents": [
    {
      "type": "prompt",
      "text": "让图片中的主体自然转头，镜头缓慢推近"
    },
    {
      "type": "first_frame",
      "url": "https://example.com/start.jpg"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5
  }
}'
4. 输出参数
同「文生视频」输出参数。
5. 响应示例
{
  "code": 0,
  "message": "success",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。
全能视频生成（Omni Video）
1. 接口描述
V3 Omni / O1 的多模态统一生成入口：可综合使用提示词、参考图片（首/尾帧、参考图）、参考视频（特征视频 / 待编辑基础视频）与元素（Element）生成或编辑视频。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/omni-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v3-omni、kling-video-o1
contents
是
array
多模态参考素材集合，同一素材的字段放在同一对象内。子字段见下表。
settings
否
object
输出配置，子字段见下表。
options
否
object
通用配置，同「文生视频」。
contents 数组元素子字段：
参数名
必选
类型
描述
type
是
string
素材类型。枚举：prompt / first_frame / last_frame / refer_image / feature_video（特征参考视频）/ base_video（待编辑基础视频）/ element。
text
条件必选
string
文本提示词，type=prompt 时必选。≤ 2500 字符（V3 Omni 建议 ≤ 2500，上限 3072）；支持 @xxx 素材引用与多镜头语法（V3 Omni）。
url
条件必选
string
图片/视频素材。图片支持 URL 或 Base64；视频仅支持 URL。图片约束：jpg/jpeg/png，≤ 50MB，宽高 ≥ 300px，宽高比 1:2.5~2.5:1。视频约束：mp4/mov，≤ 200MB，V3 Omni 时长 3~15.5s / O1 时长 3~10s。
element_id
条件必选
string
元素 ID（由元素管理接口创建），type=element 时必选。O1 当前仅支持多图元素。
settings 子字段：
子字段
必选
描述
resolution
否
清晰度。V3 Omni：720p / 1080p / 4k；O1：720p / 1080p。默认值：720p。
aspect_ratio
条件必选
画面宽高比：16:9 / 9:16 / 1:1，默认 16:9。当无首帧且无参考视频时必填。
duration
否
时长（秒）。V3 Omni：3~15；O1：3~10（O1 仅用首帧且无其他参考时仅支持 5 / 10）。默认值：5。
multi_shot
否
仅 V3 Omni。是否生成多镜头视频，默认 true。
audio
否
音频。V3 Omni：native / original / off（默认 off）；O1：original / off（默认 off）。original=保留参考视频原声。
注意：
输入组合限制：
首尾帧仅支持「仅首帧」「首帧+尾帧」；O1 使用首尾帧时不可再加参考图与元素。
参考视频最多 1 个；feature_video 不支持尾帧，base_video 不支持首/尾帧与多镜头。
参考图与元素数量：无参考视频时总数 ≤ 7，有参考视频时 ≤ 4。
V3 Omni 使用 feature_video 时 audio 只能为 off、multi_shot 只能为 true；使用 base_video 时 audio 不能为 native（可为 original 或 off）、不支持多镜头。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/omni-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-v3-omni",
  "contents": [
    {
      "type": "prompt",
      "text": "Change the color of the parrots feathers to blue, keeping the background unchanged"
    },
    {
      "type": "base_video",
      "url": "https://example.com/input.mp4"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "duration": 5,
    "audio": "original"
  }
}'
说明：
将示例中的 model 替换为 kling-video-o1，即可调用 O1 模型（注意 O1 时长上限为 10 秒，且无 multi_shot 参数）。
4. 输出参数
同「文生视频」输出参数。
5. 响应示例
{
  "code": 0,
  "message": "success",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。
元素管理（Element）
1. 接口描述
用于创建、查询与删除自定义元素（定制主体）。元素基于多张参考图创建，创建后可在图生视频、全能视频生成接口中通过 element_id 引用，实现定制角色的复用。
接口：
创建：POST https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements
查询：GET https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements/{id}
删除：POST https://tokenhub.tencentmaas.com/v1/wand/kling/delete-advanced-elements
2. 输入参数
创建：
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v3、kling-video-v3-omni（O1 元素管理无需 model 字段）。
element_name
是
string
元素名称，≤ 20 字符。示例："my_hero"。
element_description
是
string
元素描述，≤ 100 字符。
reference_type
是
string
引用方式。取值：image_refer（多图元素）。
element_image_list
是
object
多图参考对象。含 frontal_image（≥1 张正面图）与 refer_images[].image_url（1~3 张不同角度/特写图）。图片支持公网 URL 或 Base64 传入。约束：jpg/jpeg/png，≤ 10MB，宽高 ≥ 300px，宽高比 1:2.5~2.5:1。
tag_list
否
array
标签配置，结构 [{ "tag_id": "o_101" }]。tag_id 枚举：o_101 Hottest / o_102 Character / o_103 Animal / o_104 Item / o_105 Costume / o_106 Scene / o_107 Effect / o_108 Others。
external_task_id
否
string
自定义任务 ID，账号内唯一。
查询与删除：
参数名
必选
类型
描述
task_id
是（查询）
string
元素创建任务的任务 ID，填入查询路径 {id}；也可用创建时的 external_task_id 替代。
element_id
是（删除）
string
要删除的元素 ID；仅支持删除自定义元素，官方元素（owned_by=kling）不可删除。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-v3",
  "element_name": "my_hero",
  "element_description": "短发年轻男性，穿蓝色夹克",
  "reference_type": "image_refer",
  "element_image_list": {
    "frontal_image": "https://example.com/front.jpg",
    "refer_images": [
      { "image_url": "https://example.com/side.jpg" }
    ]
  }
}'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息。
request_id
string
请求 ID。
data.task_id
string
任务 ID，由系统生成。
data.task_status
string
任务状态：submitted / processing / succeed / failed。
data.task_info.external_task_id
string
自定义任务 ID（创建接口返回）。
data.created_at / data.updated_at
number
任务创建 / 更新时间；Unix 毫秒时间戳。
查询接口额外返回 data.task_result.elements[]：element_id、element_name、reference_type、element_image_list、tag_list、owned_by、status（succeed / deleted）。查询响应还包含 usage（用量消耗，含 usage.total_tokens）字段。
5. 响应示例
{
  "code": 0,
  "message": "success",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "task_id": "task_xxxxxxxxxxxx",
    "task_status": "submitted",
    "created_at": 1714000000000,
    "updated_at": 1714000000000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。查询接口中任务失败原因见 data.task_status_msg。
查询任务结果
1. 接口描述
各生成接口（文生/图生/全能）共用的任务查询方式：提交任务返回任务 ID 后，通过统一的任务查询端点轮询任务状态，成功后从结果中获取视频地址。
接口： GET https://tokenhub.tencentmaas.com/v1/wand/kling/tasks/{task_id}
说明：
路径中的 {task_id} 即提交任务时返回的 data.id（示例中以 YOUR_TASK_ID 占位）。视频生成约需数分钟，建议每 3~5 秒轮询一次。响应字段按可灵官方 API 结构给出，以实际返回为准。
2. 输入参数
参数名
必选
类型
描述
task_id
是
string
任务 ID（路径参数），即提交任务时返回的 data.id
3. 请求示例
curl -X GET 'https://tokenhub.tencentmaas.com/v1/wand/kling/tasks/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息。
request_id
string
请求 ID。
data
array
任务结果列表。
data[].id
string
任务 ID。
data[].status
string
任务状态：submitted / processing / succeeded / failed。
data[].message
string
任务状态信息；任务失败时展示失败原因。
data[].outputs
array
视频结果列表。
data[].outputs[].type
string
生成结果类型；当前视频结果为 video。
data[].outputs[].id
string
视频 ID。
data[].outputs[].url
string
视频文件地址，为临时地址，请及时下载转存。
data[].outputs[].duration
string
视频时长（秒）。
data[].create_time
long
任务创建时间；Unix 毫秒时间戳。
data[].update_time
long
任务更新时间；Unix 毫秒时间戳。
usage
object
用量消耗。
usage.total_tokens
integer
本次任务消耗的 token 数，用于计费/对账。
5. 响应示例
{
  "code": 0,
  "data": [
    {
      "update_time": 1786429168170,
      "create_time": 1786428992000,
      "id": "251435731-WandVideo-7d1997fb7ad74bfabd2814b4a9962571",
      "message": "",
      "outputs": [
        {
          "duration": "10.041",
          "id": "916037982829322296",
          "type": "video",
          "url": "https://aigc-output-video-1326893053.cos.ap-guangzhou.myqcloud.com/251435731/251435731-WandVideo-7d1997fb7ad74bfabd2814b4a9962571_0.mp4?q-sign-algorithm\\u003dsha1\\u0026q-ak\\u003dAKIDLm5EG5h5KPH3ueDZk04xgDZikeLrAG9C\\u0026q-sign-time\\u003d1786429156;1786472366\\u0026q-key-time\\u003d1786429156;1786472366\\u0026q-header-list\\u003dhost\\u0026q-url-param-list\\u003d\\u0026q-signature\\u003d97463f31176396d8962187c0d424ec3a9a91387c"
        }
      ],
      "status": "succeeded"
    }
  ],
  "message": "SUCCEED",
  "request_id": "5d0b35d5-da56-4dae-8e6c-81035122e716-query-1786429167",
  "usage": {
    "total_tokens": 600000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。
附录
统一错误码
HTTP 状态码
业务码
错误信息
说明
200
0
success
请求成功
401
1000
Authentication failed
Authorization 缺失或 apikey 非法
401
1001
Authorization is empty
未携带 Authorization 头
401
1002
Authorization is invalid
apikey 无效或已失效
401
1003
Authorization is not yet valid
apikey 尚未生效
401
1004
Authorization has expired
apikey 已过期
429
1100
Account exception
账号异常（可能欠费、被封禁或被暂停）
429
1101
Account in arrears (postpaid)
后付费账号欠费
429
1102
Resource pack depleted or expired
资源包已用完或已过期
403
1103
Access denied for the requested resource
请求资源无访问权限（未订阅对应模型/能力）
400
1200
Invalid request parameters
请求参数非法（缺失必选项、类型错误、枚举越界等）
400
1201
Invalid parameters
参数值不合法，请对照文档参数取值范围检查
404
1202
The requested method is invalid
HTTP 方法错误
404
1203
The requested resource does not exist
端点路径错误或资源不存在
400
1300
Trigger the platform strategy
触发平台策略（如内容审核不通过、违规输入）
400
1301
Trigger platform sensitive word list
命中敏感词或违规提示词
429
1302
Too frequent API calls
调用过于频繁，触发限流
429
1303
Concurrency or QPS exceeds the limit
并发或 QPS 超过预设配额
400
1304
Trigger IP strategy
触发 IP 策略拦截
500
5000
Internal server error
服务器内部错误
503
5001
Server is temporarily unavailable
服务暂不可用（多为忙碌或维护中）
504
5002
Server internal timeout
服务内部超时
多镜头（Multi-shot）提示词语法
格式：shot n, m, words; shot n, m, words;，使用半角分号分隔各分镜。
n：镜头序号，最少 1 个、最多 6 个分镜。
m：镜头时长（秒），每个镜头 ≥ 1s，且所有分镜时长之和须等于视频总时长（duration）。
words：该镜头的提示词，最大长度 512 字符。
提示词整体最大长度 3072 字符（建议 ≤ 2500），支持正向 / 负向描述。
仅 kling-video-v3、kling-video-v3-omni 支持，需 multi_shot=true（默认）方可生效。
图片素材通用约束
格式 .jpg / .jpeg / .png（不支持透明通道）；文件 ≤ 50MB；宽高均 ≥ 300px；宽高比 1:2.5 ~ 2.5:1；支持 URL 或 Base64 传入。
常见问题
1. 六款模型如何选择？
能力最全、要 4K / 原生音频 / 多镜头 / 元素：kling-video-v3。
多模态混合输入、视频编辑：kling-video-v3-omni 或 kling-video-o1（O1 时长上限 10 秒）。
批量生成、速度成本优先：kling-video-v3-turbo（不支持音频与多镜头）。
需要原生音频、参数适中：kling-video-v2.6。
参数最简单、纯入门：kling-video-v2.5-turbo。
2. 图生视频能指定画面宽高比吗？
不能。图生视频的输出画幅由输入图片决定，无 aspect_ratio 参数；仅文生视频、全能视频生成支持该参数（全能视频生成在无首帧且无参考视频时必填）。
3. 自定义元素（Element）是什么，怎么用？
元素是基于多张参考图创建的定制视觉主体（人物形象等），通过元素管理接口创建后获得 element_id，可在图生视频、全能视频生成中引用，用于跨任务保持角色一致。在提示词中以 @元素名 引用，注意元素名之间避免互为子串。
﻿

模型名称	model 参数值	支持能力	视频时长（秒）	清晰度档位	画面宽高比（文生/全能）	选型建议
Kling-Video-V3	`kling-video-v3`	文生 / 图生（含首尾帧、元素）	3 ~ 15	720p / 1080p / 4k	16:9、9:16、1:1	旗舰款：支持原生音频、多镜头、元素引用与 4K，能力最全
Kling-Video-V3-omni	`kling-video-v3-omni`	全能视频生成（文/图/视频多模态输入、视频编辑）	3 ~ 15	720p / 1080p / 4k	16:9、9:16、1:1	需要参考视频、视频编辑等多模态混合输入场景
Kling-Video-V3-turbo	`kling-video-v3-turbo`	文生 / 图生	3 ~ 15	720p / 1080p	16:9、9:16、1:1	V3 快速版，生成更快、成本更低，适合批量生成；参数精简（无音频、多镜头）
Kling-Video-O1	`kling-video-o1`	全能视频生成（多模态统一入口）	3 ~ 10	720p / 1080p	16:9、9:16、1:1	O1 系列多模态统一生成入口
Kling-Video-V2.6	`kling-video-v2.6`	文生 / 图生（含首尾帧）	5 / 10	720p / 1080p	16:9、9:16、1:1	支持原生音频的成熟方案
Kling-Video-V2.5-turbo	`kling-video-v2.5-turbo`	文生 / 图生（含首尾帧）	5 / 10	720p / 1080p	16:9、9:16、1:1	参数最精简的入门款，成本敏感场景

参数名	必选	类型	描述
model	是	string	模型版本。取值：`kling-video-v2.5-turbo`、`kling-video-v2.6`、`kling-video-v3-turbo`、`kling-video-v3`
prompt	是	string	提示词，可包含正向与负向描述。V3：≤ 3072 字符（建议 ≤ 2500），支持多镜头模板语法；V3 Turbo / V2.6 / V2.5 Turbo：≤ 2500 字符。
settings	否	object	输出配置，子字段见下表（各模型支持的字段不同）。

子字段	适用模型	描述
resolution	全部	清晰度。V3：720p / 1080p / 4k；其余：720p / 1080p。默认值：720p。
aspect_ratio	全部	画面宽高比。枚举：16:9 / 9:16 / 1:1。默认值：16:9。
duration	全部	时长（秒）。V3 / V3 Turbo：3~15 整数；V2.6 / V2.5 Turbo：5 / 10。默认值：5。
multi_shot	仅 V3	是否生成多镜头视频，默认 true；设为 false 时多镜头提示词不产生多镜头输出。
audio	仅 V3 / V2.6	音频。枚举：native（生成与画面匹配的原生音频）/ off（默认）。注意：V2.6 文生视频在 audio=native 时仅支持 1080p。

字段	类型	说明
code	int	业务错误码；0 表示成功，其它值见附录：统一错误码。
message	string	错误或提示信息；成功时通常为 "success" 或空字符串。
request_id	string	请求 ID，由系统生成，用于问题追踪与排查。
data	object	任务数据对象。
data.id	string	系统生成的任务 ID，用于后续任务查询。
data.status	string	任务状态：submitted / processing / succeeded / failed。
data.create_time	long	任务创建时间；Unix 时间戳，单位毫秒。
data.update_time	long	任务更新时间；Unix 时间戳，单位毫秒。
data.external_id	string	自定义任务 ID（请求中传入了 external_task_id 时回显）。

status	含义	处理建议
submitted	已提交	继续轮询。
processing	处理中	继续轮询。
succeeded	生成成功	从查询结果中获取视频地址。
failed	生成失败	查看失败原因，修改后重试；持续失败请联系技术支持并附 request_id。

HTTP 状态码	业务码	错误信息	说明
200	0	success	请求成功
401	1000	Authentication failed	Authorization 缺失或 apikey 非法
401	1001	Authorization is empty	未携带 Authorization 头
401	1002	Authorization is invalid	apikey 无效或已失效
401	1003	Authorization is not yet valid	apikey 尚未生效
401	1004	Authorization has expired	apikey 已过期
429	1100	Account exception	账号异常（可能欠费、被封禁或被暂停）
429	1101	Account in arrears (postpaid)	后付费账号欠费
429	1102	Resource pack depleted or expired	资源包已用完或已过期
403	1103	Access denied for the requested resource	请求资源无访问权限（未订阅对应模型/能力）
400	1200	Invalid request parameters	请求参数非法（缺失必选项、类型错误、枚举越界等）
400	1201	Invalid parameters	参数值不合法，请对照文档参数取值范围检查
404	1202	The requested method is invalid	HTTP 方法错误
404	1203	The requested resource does not exist	端点路径错误或资源不存在
400	1300	Trigger the platform strategy	触发平台策略（如内容审核不通过、违规输入）
400	1301	Trigger platform sensitive word list	命中敏感词或违规提示词
429	1302	Too frequent API calls	调用过于频繁，触发限流
429	1303	Concurrency or QPS exceeds the limit	并发或 QPS 超过预设配额
400	1304	Trigger IP strategy	触发 IP 策略拦截
500	5000	Internal server error	服务器内部错误
503	5001	Server is temporarily unavailable	服务暂不可用（多为忙碌或维护中）
504	5002	Server internal timeout	服务内部超时

Kling 调用指南

本页目录：

概述

前提条件

调用流程

模型列表

文生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

图生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

全能视频生成（Omni Video）

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

元素管理（Element）

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

查询任务结果

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

附录

统一错误码

多镜头（Multi-shot）提示词语法

图片素材通用约束

常见问题

1. 六款模型如何选择？

2. 图生视频能指定画面宽高比吗？

3. 自定义元素（Element）是什么，怎么用？