大模型服务平台 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，从结果中获取视频地址。
模型列表
模型名称
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
输出配置，子字段见下表（各模型支持的字段不同）。
options
否
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。
options 子字段：
子字段
必选
描述
external_task_id
否
自定义任务 ID，账号内唯一，支持通过该 ID 查询任务。
watermark_info
否
水印配置。结构：{"enabled": true/false}，true 为开启水印。
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
错误或提示信息；成功时为 "SUCCEED"。
request_id
string
请求 ID，由系统生成，用于问题追踪与排查。
data
object
任务数据对象。
data.id
string
系统生成的任务 ID，用于后续任务查询。
data.status
string
任务状态；提交成功时固定为 submitted，后续状态通过查询接口获取。
data.message
string
任务状态信息；任务失败时展示失败原因。
data.create_time
long
任务创建时间；Unix 时间戳，单位毫秒。
data.update_time
long
任务更新时间；Unix 时间戳，单位毫秒。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务提交成功后，生成阶段的任务状态通过 查询任务结果 接口获取：
status
含义
处理建议
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 / voice；V3 Turbo：prompt / first_frame；V2.5 Turbo：prompt / first_frame / last_frame。
text
条件必选
string
文本提示词，type=prompt 时必选。≤ 2500 字符；V3 支持多镜头模板语法与 @元素 引用；可通过 @id 引用音色素材。
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 引用。
voice_id
条件必选
string
音色 ID，type=voice 时必选。由「音色管理」创建后查询获得，也可使用系统预置音色。
id
条件必选
string
素材索引 ID，type=voice 时必选；同一任务内不得重复，在 prompt 中以 @id 形式引用该音色。
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）。
音色（type=voice）至多引用 2 个；指定音色时 settings.audio 不能为 off（生成无声视频时不支持指定音色）。
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": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "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 / voice（音色）。
text
条件必选
string
文本提示词，type=prompt 时必选。≤ 2500 字符（V3 Omni 建议 ≤ 2500，上限 3072）；支持 @xxx 素材引用与多镜头语法（V3 Omni）；可通过 @id 引用音色素材。
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 当前仅支持多图元素。
voice_id
条件必选
string
音色 ID，type=voice 时必选。由「音色管理」创建后查询获得，也可使用系统预置音色。
id
条件必选
string
素材索引 ID，type=voice 时必选；同一任务内不得重复，在 prompt 中以 @id 形式引用该音色。
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。
音色（type=voice）至多引用 2 个；指定音色时 settings.audio 不能为 off。
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": "SUCCEED",
  "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "data": {
    "id": "task_xxxxxxxxxxxx",
    "status": "submitted",
    "message": "",
    "create_time": 1714000000000,
    "update_time": 1714000000000
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。
元素管理（Element）
元素管理用于创建、查询与删除自定义主体（定制角色）。主体可基于多张参考图（image_refer）或参考视频（video_refer）创建，创建后可在图生视频、全能视频生成接口中通过 element_id 引用，实现定制角色的复用。
创建主体
1. 接口描述
创建自定义主体。创建为异步任务，提交后通过「查询主体」接口轮询任务状态，成功后获得 element_id。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements
2. 输入参数
参数名
必选
类型
描述
element_name
是
string
元素名称，≤ 20 字符。示例："my_hero"。
element_description
是
string
元素描述，≤ 100 字符。
reference_type
是
string
参考方式。取值：image_refer（多图主体）/ video_refer（视频主体）。
element_image_list
条件必选
object
多图参考对象，reference_type=image_refer 时必填。含 frontal_image（≥1 张正面图）与 refer_images[].image_url（1~3 张不同角度/特写图）。图片支持公网 URL 或 Base64 传入。约束：jpg/jpeg/png，≤ 10MB，宽高 ≥ 300px，宽高比 1:2.5~2.5:1。
element_video_list
条件必选
object
视频参考对象，reference_type=video_refer 时必填。结构：{"refer_videos": [{"video_url": "..."}]}。约束：MP4/MOV，时长 3~8s，1080P，宽高比 16:9 或 9:16，≤ 200MB。
element_voice_id
否
string
绑定音色库中已有音色的 ID；为空则不绑定音色。
tag_list
否
array
标签配置，结构 [{ "tag_id": "o_101" }]。tag_id 枚举：o_101 热梗 / o_102 人物 / o_103 动物 / o_104 道具 / o_105 服饰 / o_106 场景 / o_107 特效 / o_108 其他。
external_task_id
否
string
自定义任务 ID，账号内唯一。
3. 请求示例
多图主体（image_refer）：
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 '{
  "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" }
    ]
  }
}'
视频主体（video_refer）：
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 '{
  "element_name": "my_hero",
  "element_description": "短发年轻男性，穿蓝色夹克",
  "reference_type": "video_refer",
  "element_video_list": {
    "refer_videos": [
      { "video_url": "https://example.com/demo.mp4" }
    ]
  }
}'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息；成功时为 "SUCCEED"。
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.task_status_msg
string
任务失败时展示失败原因，正常为空字符串。
data.created_at
number
任务创建时间，Unix 毫秒时间戳。
data.updated_at
number
任务最后更新时间，Unix 毫秒时间戳。
data.final_unit_deduction
string
任务最终扣减积分数值。
data.final_balance_deduction.quota
string
额度扣减折扣价。
data.final_balance_deduction.list_price
string
额度扣减刊例价。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "02f9537c-9319-4cfb-b347-8f22cb73ffc8",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1787836125041,
    "updated_at": 1787836125041
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。
查询主体
1. 接口描述
查询主体创建任务状态及创建结果。提交创建任务返回任务 ID 后，通过本接口轮询直至 data.task_status = succeed，从 data.task_result.elements[] 获取主体信息。
接口： GET https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements/{id}
说明：
路径中的 {id} 为创建任务返回的 data.task_id，也可用创建时传入的 external_task_id 替代。
2. 输入参数
参数名
必选
类型
描述
task_id
是
string
元素创建任务的任务 ID，填入查询路径 {id}；也可用创建时的 external_task_id 替代。
3. 请求示例
curl -X GET 'https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息；成功时为 "SUCCEED"。
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.task_status_msg
string
任务失败时展示失败原因，正常为空字符串。
data.task_result.elements[]
array
主体列表，task_status=succeed 时返回。
data.task_result.elements[].element_id
number
主体 ID，全局唯一。
data.task_result.elements[].element_name
string
主体名称。
data.task_result.elements[].element_description
string
主体描述。
data.task_result.elements[].element_type
string
参考方式：image_refer（多图主体）/ video_refer（视频主体）。
data.task_result.elements[].element_image_list
object
图片参考信息（image_refer 时有值）。含 frontal_image 与 refer_images[].image_url。
data.task_result.elements[].element_video_list
object
视频参考信息（video_refer 时有值）。
data.task_result.elements[].owned_by
string
主体来源；kling 为官方主体库，其他为创作者 ID。
data.task_result.elements[].status
string
主体状态：succeed（正常）/ deleted（已删除）。
data.created_at
number
任务创建时间，Unix 毫秒时间戳。
data.updated_at
number
任务最后更新时间，Unix 毫秒时间戳。
data.final_unit_deduction
string
任务最终扣减积分数值。
data.final_balance_deduction.quota
string
额度扣减折扣价。
data.final_balance_deduction.list_price
string
额度扣减刊例价。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "656ee178-de4f-48ea-9763-166bbaa3e4cc-query-1787836129",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {
      "elements": [
        {
          "element_id": 319807609263140,
          "element_name": "高级主体_图片测试",
          "element_description": "短发年轻男性，穿蓝色夹克",
          "element_type": "image_refer",
          "element_image_list": {
            "frontal_image": "https://example.com/front.jpg",
            "refer_images": [
              { "image_url": "https://example.com/side.jpg" }
            ]
          },
          "element_video_list": {},
          "owned_by": "826925436873121851",
          "status": "succeed"
        }
      ]
    },
    "task_status_msg": "",
    "created_at": 1787836125041,
    "updated_at": 1787836128102,
    "final_unit_deduction": "0",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务失败原因见 data.task_status_msg。
删除主体
1. 接口描述
删除自定义主体。仅支持删除自定义元素，官方元素（owned_by=kling）不可删除。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/delete-advanced-elements
2. 输入参数
参数名
必选
类型
描述
element_id
是
string
要删除的元素 ID。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/delete-advanced-elements' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "element_id": "319807609263140"
}'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息；成功时为 "SUCCEED"。
request_id
string
请求 ID，由系统生成，用于问题追踪与排查。
data.task_id
string
任务 ID，由系统生成。
data.task_status
string
任务状态：submitted（已提交）/ processing（处理中）/ succeed（成功）/ failed（失败）。
data.task_status_msg
string
任务失败时展示失败原因，正常为空字符串。
data.created_at
number
任务创建时间，Unix 毫秒时间戳。
data.updated_at
number
任务最后更新时间，Unix 毫秒时间戳。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "dd4a503f-8afd-415d-b3e8-de4c26d4f87a",
  "data": {
    "task_id": "921939922066997283",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {},
    "task_status_msg": "",
    "created_at": 1787836125041,
    "updated_at": 1787836128102,
    "final_unit_deduction": "0",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。
音色管理（Voice）
音色管理用于创建、查询与删除自定义音色。音色基于参考音频（或含音频的视频）创建，创建后可在图生视频（contents 中 type=voice 素材）、数字人（avatar）、对口型（advanced-lip-sync）等接口中通过 voice_id 引用。
音色创建为异步任务，统一分两步：
1. 提交任务：调用创建接口，成功返回 data.task_id（任务 ID）；
2. 轮询结果：携带任务 ID 调用「查询音色任务」接口，直至 data.task_status = succeed，从 data.task_result.voices[] 中获取 voice_id。
创建音色
1. 接口描述
基于参考音频（或含音频的视频）创建自定义音色。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/custom-voices
2. 输入参数
参数名
必选
类型
描述
voice_name
是
string
音色名称。
voice_url
条件必选
string
参考音频的公网 URL。与 video_id 二选一。
video_id
条件必选
string
含目标音频的视频 ID（视频生成任务产出的视频）。与 voice_url 二选一。
external_task_id
否
string
自定义任务 ID，账号内唯一。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/custom-voices' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "voice_name": "测试音色",
  "voice_url": "https://example.com/reference.mp3"
}'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息；成功时为 "SUCCEED"。
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
number
任务创建时间，Unix 毫秒时间戳。
data.updated_at
number
任务最后更新时间，Unix 毫秒时间戳。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "a90bd11c-f272-4686-bad9-72310898a217",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "submitted",
    "task_info": {},
    "created_at": 1786687976483,
    "updated_at": 1786687976483
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。
查询音色任务
1. 接口描述
携带创建接口返回的任务 ID 轮询音色创建任务，任务成功后从结果中获取 voice_id 与试听地址。
接口： GET https://tokenhub.tencentmaas.com/v1/wand/kling/custom-voices/{task_id}
说明：
路径中的 {task_id} 即创建接口返回的 data.task_id；也可用创建时传入的 external_task_id 替代。建议每 2~3 秒轮询一次。
2. 输入参数
参数名
必选
类型
描述
task_id
是
string
任务 ID（路径参数），即创建接口返回的 data.task_id。
3. 请求示例
curl -X GET 'https://tokenhub.tencentmaas.com/v1/wand/kling/custom-voices/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息；成功时为 "SUCCEED"。
request_id
string
请求 ID。
data.task_id
string
任务 ID。
data.task_status
string
任务状态：submitted（已提交）/ processing（处理中）/ succeed（成功）/ failed（失败）。
data.task_status_msg
string
任务状态信息；任务失败时展示失败原因。
data.task_info.external_task_id
string
自定义任务 ID（创建时传入则回显）。
data.task_result.voices[]
array
音色列表，task_status=succeed 时返回。
data.task_result.voices[].voice_id
string
音色 ID，用于数字人、对口型等接口引用。
data.task_result.voices[].voice_name
string
音色名称。
data.task_result.voices[].trial_url
string
音色试听音频地址，为临时地址，请及时下载转存。
data.task_result.voices[].owned_by
string
音色归属方标识。
data.task_result.voices[].status
string
音色状态：succeed（正常）/ deleted（已删除）。
data.created_at
number
任务创建时间，Unix 毫秒时间戳。
data.updated_at
number
任务最后更新时间，Unix 毫秒时间戳。
data.final_unit_deduction
string
本次任务扣费数量。
data.final_balance_deduction.quota
string
额度扣减折扣价。
data.final_balance_deduction.list_price
string
额度扣减刊例价。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "8efcf51b-4637-4616-a21b-436501eaef96-query-1786687983",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {
      "voices": [
        {
          "voice_id": "917124264959582304",
          "voice_name": "测试音色",
          "trial_url": "https://v4-kling.kechuangai.com/bs2/upload-ylab-stunt/muse/826925436873121851/AUDIO/20260814/45239c369821b72b9683f775e569afa5-84ca38da-26fe-46d5-aee7-67982729af58.quality.wav?x-kcdn-pid=113274",
          "owned_by": "826925436873121851",
          "status": "succeed"
        }
      ]
    },
    "task_status_msg": "",
    "created_at": 1786687976483,
    "updated_at": 1786687982942,
    "final_unit_deduction": "0.05",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务失败原因见 data.task_status_msg。
删除音色
1. 接口描述
删除指定的自定义音色，仅支持删除自定义音色。删除后该音色不可再在生成接口中引用。
接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/delete-voice
2. 输入参数
参数名
必选
类型
描述
voice_id
是
string
要删除的音色 ID（查询接口返回的 voice_id）。
3. 请求示例
curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/kling/delete-voice' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "voice_id": "917124264959582304"
}'
4. 输出参数
字段
类型
说明
code
int
业务错误码；0 表示成功。
message
string
错误或提示信息；成功时为 "SUCCEED"。
request_id
string
请求 ID。
data.task_id
string
该音色对应的创建任务 ID。
data.task_status
string
任务状态：submitted（已提交）/ processing（处理中）/ succeed（成功）/ failed（失败）。
data.task_result
object
删除结果对象（通常为空对象 {}，即表示删除成功）。
data.task_status_msg
string
任务失败时展示失败原因，正常为空字符串。
data.created_at
number
任务创建时间，Unix 毫秒时间戳。
data.updated_at
number
任务最后更新时间，Unix 毫秒时间戳。
5. 响应示例
{
  "code": 0,
  "message": "SUCCEED",
  "request_id": "b641fc55-7f23-41e5-8155-2fa371c3d871",
  "data": {
    "task_id": "917124237444943953",
    "task_status": "succeed",
    "task_info": {},
    "task_result": {},
    "task_status_msg": "",
    "created_at": 1786687976483,
    "updated_at": 1786687982942,
    "final_unit_deduction": "0.05",
    "final_balance_deduction": {
      "quota": "0",
      "list_price": "0"
    }
  }
}
6. 错误码
请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。
查询任务结果
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
任务状态：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 毫秒时间戳。
tokenhub_usage
object
用量消耗。
tokenhub_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",
  "tokenhub_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）是什么，怎么用？
元素是基于多张参考图（image_refer）或参考视频（video_refer）创建的定制视觉主体（人物形象等），通过元素管理接口创建后获得 element_id，可在图生视频、全能视频生成中引用，用于跨任务保持角色一致。在提示词中以 @元素名 引用，注意元素名之间避免互为子串。
4. 自定义音色（Voice）是什么，怎么用？
音色是基于参考音频（或含音频的视频）创建的定制声音主体，通过音色管理接口创建后获得 voice_id，可在数字人（avatar）、对口型（advanced-lip-sync）等接口中引用。查询结果中的 trial_url 为临时试听地址，请及时下载转存。
﻿

模型名称	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	输出配置，子字段见下表（各模型支持的字段不同）。
options	否	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	错误或提示信息；成功时为 "SUCCEED"。
request_id	string	请求 ID，由系统生成，用于问题追踪与排查。
data	object	任务数据对象。
data.id	string	系统生成的任务 ID，用于后续任务查询。
data.status	string	任务状态；提交成功时固定为 submitted，后续状态通过查询接口获取。
data.message	string	任务状态信息；任务失败时展示失败原因。
data.create_time	long	任务创建时间；Unix 时间戳，单位毫秒。
data.update_time	long	任务更新时间；Unix 时间戳，单位毫秒。

status	含义	处理建议
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. 错误码

删除主体

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

音色管理（Voice）

创建音色

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

查询音色任务

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

删除音色

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

查询任务结果

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

附录

统一错误码