产品公告
产品简介
- 产品概述
- 模型列表
产品计费
快速入门
Token Plan
- Token Plan 企业版
- Token Plan 个人版
调用指南
- API 使用说明
- 语言模型
- 向量模型
- API 错误码说明
- 图像生成模型
- 视频生成模型
- 3D 生成模型
- 语音生成模型
接入 AI 工具
平台功能
- 模型广场
- 体验中心
- 启用管理
- 在线推理
- 用量统计
- 模型监控
- 监控告警
- API Key 管理
- 平台配置
管控面 API
- History
- Introduction
- API Category
- Making API Requests
- API Key Management APIs
- Terminology Library Management APIs
- Token Plan Package Purchasing APIs
- Token Plan Management APIs
- TokenPlan APIKey Management APIs
- Token Plan Call Detail APIs
- Usage Statistics APIs
- Data Types
- Error Codes
常见问题
相关协议
词汇表

Kling 生视频调用指南

下载

聚焦模式

字号

最后更新时间： 2026-10-23 23:19:44

本文档已由 AI 辅助审校

概述
可灵（Kling）是快手推出的视频生成模型系列，支持文生视频、图生视频、全能视频生成（Omni）、动作控制等能力，并配套元素管理（自定义主体）与音色管理（自定义音色）接口。
本文介绍如何通过 TokenHub 调用可灵的模型：kling-video-v4、kling-video-v3、kling-video-v3-turbo、kling-video-v3-omni、kling-video-motion-control-v3.0、kling-video-motion-control-v2.6。
前提条件
已 注册腾讯云 账号并开通 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-v4
kling-video-v4
文生 / 图生（含首尾帧）/ 全能视频生成（参考图、参考视频、主体、音色混合输入）
3 ~ 30
720p / 1080p
21:9、16:9、9:16、1:1；全能另支持 adaptive
新一代旗舰：单次最长 30 秒，支持 21:9 宽画幅，全能视频生成单任务最多组合 15 项参考素材
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-Motion-Control-V3.0
kling-video-motion-control-v3.0
动作控制（形象参考图 + 动作参考视频，支持引用主体）
跟随动作参考视频（3 ~ 30s）
720p / 1080p
跟随输入素材
让形象参考图中的人物复刻参考视频的动作；支持引用 1 个主体
Kling-Video-Motion-Control-V2.6
kling-video-motion-control-v2.6
动作控制（形象参考图 + 动作参考视频）
跟随动作参考视频（3 ~ 30s）
720p / 1080p
跟随输入素材
动作控制上一代版本，不支持引用主体
说明：
「画面宽高比」列为文生视频、全能视频生成支持的取值范围；图生视频、首尾帧生视频无 aspect_ratio 参数，输出画幅跟随输入图片比例。动作控制同样无 aspect_ratio 参数，输出画幅跟随输入素材。kling-video-v4 全能视频生成的 aspect_ratio 默认为 adaptive，由模型根据输入素材自动选择画幅。
文生视频
1. 接口描述
仅凭文本提示词生成视频。v4 单次最长 30 秒，支持 21:9 宽画幅；V3 支持多镜头模板语法（详情请参见「附录：多镜头（Multi-shot）提示词语法」）、原生音频与 4K 输出。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v4、kling-video-v3、kling-video-v3-turbo
prompt
是
string
提示词，可包含正向与负向描述。v4：纯英文 ≤ 26000 字符，纯非英文 ≤ 11000 字符，中英混合时需满足 英文字符数 ÷ 26000 + 非英文字符数 ÷ 11000 ≤ 1；V3：≤ 3072 字符（建议 ≤ 2500），支持多镜头模板语法；V3 Turbo：≤ 2500 字符。
settings
否
object
输出配置，子字段见下表（各模型支持的字段不同）。
options
否
object
通用配置，子字段见下表。
settings 子字段（按模型）：
子字段
适用模型
描述
resolution
全部
清晰度。V3：720p / 1080p / 4k；v4 / V3 Turbo：720p / 1080p。默认值：v4 为 1080p，其余为 720p。
aspect_ratio
全部
画面宽高比。枚举：16:9 / 9:16 / 1:1（v4 另支持 21:9）。默认值：16:9。
duration
全部
时长（秒）。v4：3 ~ 30 的整数；V3 / V3 Turbo：3 ~ 15 的整数。默认值：5。
multi_shot
仅 V3
是否生成多镜头视频，默认 true；设为 false 时多镜头提示词不产生多镜头输出。
audio
仅 V3
音频。枚举：native（生成与画面匹配的原生音频）/ off（默认）。
说明：
kling-video-v4、kling-video-v3-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-intl.tencentcloudmaas.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-v4 或 kling-video-v3-turbo，即可调用对应模型（注意 v4 与 V3 Turbo 不支持 audio / multi_shot 字段，调用时需删去 audio 字段）。
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. 接口描述
以图片为首帧（v4 / V3 可选尾帧）结合文本提示词生成视频。V3 额外支持元素引用（Element）。图片直接传入公网 URL 或 Base64，输出画幅跟随输入图片。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v4、kling-video-v3、kling-video-v3-turbo
contents
是
array
参考素材集合，同一素材的字段放在同一对象内；至少包含一个 prompt 与一个 first_frame。子字段见下表。
settings
否
object
输出配置，子字段见下表。注意：图生视频无 aspect_ratio 参数，画幅由输入图片决定。
options
否
object
通用配置，同「文生视频」。
contents 数组元素子字段：
参数名
必选
类型
描述
type
是
string
素材类型。各模型支持：v4：prompt / first_frame / last_frame；V3：prompt / first_frame / last_frame / element；V3 Turbo：prompt / first_frame。
text
条件必选
string
文本提示词，type=prompt 时必选。≤ 2500 字符（v4 长度限制同文生视频）；V3 支持多镜头模板语法与 @元素 引用。
url
条件必选
string
图片 contents[].url（type=first_frame/last_frame）：支持 1张-2张图片输入， 支持 URL 和 Base64格式，图片格式：jpg/jpeg/png，宽高≥300px，宽高比 1：2.5~2.5：1；单张图片大小<=50MB（v4 单张 ≤ 30MB）
1. Base64：所有图片大小和<75MB，转为 Base64大小和<=100MB ；格式要求：data:image/<图片格式>;base64,<Base64 编码>
2. URL：需要公网可访问（http/https）
element_id
条件必选
string
元素引用（JSON 定义），type=element 时必选，仅 V3；最多 3 个，在 prompt 中以 @xxx 引用。
settings 子字段（按模型）：
子字段
适用模型
描述
resolution
全部
清晰度。V3：720p / 1080p / 4k；v4 / V3 Turbo：720p / 1080p。默认值：v4 为 1080p，其余为 720p。
duration
全部
时长（秒）。v4：3 ~ 30 的整数；V3 / V3 Turbo：3 ~ 15 的整数。默认值：5。
multi_shot
仅 V3
是否生成多镜头视频，默认 true。
audio
仅 V3
音频。枚举：native / off（默认 off）。
注意：
首尾帧仅支持「仅首帧」和「首帧+尾帧」，不支持仅尾帧。
kling-video-v4：首帧 1 张、尾帧可选 1 张；单张图片 ≤ 30MB。
元素名避免互为子串（如 @Zhang 与 @ZhangSan）。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.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
  }
}'
说明：
将示例中的 model 替换为 kling-video-v4 或 kling-video-v3-turbo，即可调用对应模型。使用首尾帧时，在 contents 中追加一项 {"type": "last_frame", "url": "尾帧图片地址"}（V3 Turbo 不支持尾帧）。
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. 接口描述
v4 / V3 Omni 的多模态统一生成入口：可综合使用提示词、参考图片（首/尾帧、参考图）、参考视频（特征视频 / 待编辑基础视频）与元素（Element）生成或编辑视频。v4 不支持待编辑基础视频（base_video），即不支持视频编辑。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-v4、kling-video-v3-omni
contents
是
array
多模态参考素材集合，同一素材的字段放在同一对象内。子字段见下表。
settings
否
object
输出配置，子字段见下表。
options
否
object
通用配置，同「文生视频」。
contents 数组元素子字段：
参数名
必选
类型
描述
type
是
string
素材类型。枚举：prompt / first_frame / last_frame / refer_image / feature_video（特征参考视频）/ base_video（待编辑基础视频）/ element / voice（音色）。v4 不支持 base_video。
text
条件必选
string
文本提示词，type=prompt 时必选。≤ 3072 字符（建议 ≤ 2500）；v4 长度限制同文生视频；支持 @xxx 素材引用与多镜头语法（多镜头仅 V3 Omni）；可通过 @id 引用音色素材。
url
条件必选
string
图片/视频素材。图片支持 URL 或 Base64；视频仅支持 URL。图片约束：jpg/jpeg/png，≤ 50MB，宽高 ≥ 300px，宽高比 1:2.5~2.5:1。视频约束：mp4/mov，≤ 200MB，时长 3~15.5s。
﻿
图片 contents[].url（type=first_frame / last_frame / refer_image）：支持 1张-2张图片输入，支持 URL 和 Base64格式，图片格式：jpg/jpeg/png，宽高≥300px，宽高比 1：2.5~2.5：1；单张图片大小<=50MB
1. Base64：所有图片大小和<75MB，转为 Base64大小和<=100MB ；格式要求：data:image/<图片格式>;base64,<Base64 编码>。注：图片 jpg 时图片格式填 jpeg。
2. URL：需要公网可访问（http/https）
﻿
视频 contents[].url（type=feature_video/base_video）：支持 1个-6个视频输入， 支持 URL 和 Base64格式，视频格式：mp4/mov，视频时长3秒-15.5秒，视频的宽度和高度尺寸应介于 700 像素和 4553 像素之间，总像素面积<= 8294400。视频的宽高比应介于 0.4 和 2 之间，视频帧速率基于 24fps 至 60fps，最多可添加 1 个参考视频，添加参考视频后，最多可添加一个视频角色元素；单个文件大小<=200MB（v4：视频仅支持 URL，单个 ≤ 300MB，单段及总时长 3~30 秒，参考视频最多 5 段；图片单张 ≤ 30MB、最多 10 张）；
1. Base64：所有视频大小和<=75MB，转为 Base64大小和<=100MB ；格式要求：data:video/<视频格式>;base64,<Base64 编码>。注：视频为 mov 时视频格式填 quicktime。
2. URL：需要公网可访问（http/https）。
element_id
条件必选
string
元素 ID（由元素管理接口创建），type=element 时必选。
voice_id
条件必选
string
音色 ID，type=voice 时必选。由「音色管理」创建后查询获得，也可使用系统预置音色。
id
条件必选
string
素材索引 ID，type=voice 时必选；同一任务内不得重复，在 prompt 中以 @id 形式引用该音色。
settings 子字段：
子字段
必选
描述
resolution
否
清晰度。V3 Omni：720p / 1080p / 4k；v4：720p / 1080p，暂不支持 4k。默认值：v4 为 1080p，V3 Omni 为 720p。
aspect_ratio
条件必选
画面宽高比。v4：21:9 / 16:9 / 9:16 / 1:1 / adaptive，默认 adaptive；V3 Omni：16:9 / 9:16 / 1:1，默认 16:9。V3 Omni 在无首帧且无参考视频时必填。
duration
否
时长（秒）。v4：3 ~ 30 的整数；V3 Omni：3 ~ 15 的整数。默认值：5。
multi_shot
否
仅 V3 Omni。是否生成多镜头视频，默认 true。
audio
否
仅 V3 Omni。 音频。枚举：native / original / off（默认 off）。original=保留参考视频原声。Kling-Video-v4 不支持该参数。
注意：
Kling-Video-v4 不支持 audio 参数。 v4 的 settings 仅支持 resolution / aspect_ratio / duration；如需指定音色，请在 contents 中使用 {"type": "voice", "voice_id": "音色ID", "id": "1"}，无需（也不支持）传 settings.audio。
v4 输入组合限制：
首尾帧仅支持「仅首帧」「首帧+尾帧」，不支持仅尾帧。
不支持 base_video（视频编辑）与 middle_frame（中间帧）；不支持 audio 参数，请勿传入。
参考图片 ≤ 10 张；参考视频 ≤ 5 段（有视频角色主体时，视频角色主体与参考视频合计 ≤ 5 个）；主体 ≤ 7 个（其中视频角色主体 ≤ 3 个）；音色 ≤ 3 个。
单次任务素材总数（图片 + 视频 + 主体 + 音色）≤ 15 个。
参考图片、参考视频、主体按传入顺序自动编号为 image_1 / video_1 / element_1，可在 prompt 中以 @image_1、@video_1、@element_1 形式引用。
引用音色时在 contents 中追加 {"type": "voice", "voice_id": "音色ID", "id": "1"}，无需传 settings.audio。
V3 Omni 输入组合限制：
首尾帧仅支持「仅首帧」「首帧+尾帧」。
参考视频最多 1 个；feature_video 不支持尾帧，base_video 不支持首/尾帧与多镜头。
参考图与元素数量：无参考视频时总数 ≤ 7，有参考视频时 ≤ 4。
音色（type=voice）至多引用 2 个；指定音色时 settings.audio 不能为 off。
使用 feature_video 时 audio 只能为 off、multi_shot 只能为 true；使用 base_video 时 audio 不能为 native（可为 original 或 off）、不支持多镜头。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.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"
  }
}'
v4 请求示例（参考图 + 特征参考视频）：
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-v4",
  "contents": [
    {
      "type": "prompt",
      "text": "参考 @image_1 的服饰，吸收 @video_1 的运动节奏，写实电影质感。"
    },
    {
      "type": "refer_image",
      "url": "https://example.com/refer.jpg"
    },
    {
      "type": "feature_video",
      "url": "https://example.com/motion.mp4"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 10
  }
}'
说明：
v4 不支持 base_video（视频编辑）与 settings.audio；引用音色时在 contents 中追加 {"type": "voice", "voice_id": "音色ID", "id": "1"} 即可。
v4 音色引用示例（contents.type=voice，不传 settings.audio）：
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-v4",
  "contents": [
    {
      "type": "prompt",
      "text": "女孩坐在行驶的列车窗边，安静地望向窗外。片刻后她起身走过过道，经过另一位乘客时轻声说 @1: \\"Excuse me.\\""
    },
    {
      "type": "refer_image",
      "url": "https://example.com/girl.jpg"
    },
    {
      "type": "voice",
      "voice_id": "829826751244537879",
      "id": "1"
    }
  ],
  "settings": {
    "resolution": "1080p",
    "aspect_ratio": "9:16",
    "duration": 5
  }
}'
说明：
voice_id 由「音色管理」创建后查询获得，也可使用系统预置音色。
id 为该音色素材的索引 ID，在 prompt 中以 @id 形式引用（如 @1），同一任务内不得重复。
音色至多引用 3 个；v4 不支持 settings.audio。
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，具体错误码及处理建议见「附录：统一错误码」。任务状态说明同「文生视频」。
动作控制（Motion Control）
1. 接口描述
用一段「动作参考视频」驱动「形象参考图」中的人物，生成动作与参考视频一致的视频；V3.0 还可通过元素（Element）直接指定定制角色。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/motion-control
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型版本。取值：kling-video-motion-control-v3.0、kling-video-motion-control-v2.6
contents
是
array
参考素材合集，需包含形象参考图与动作参考视频，可选提示词与参考主体。子字段见下表。
settings
是
object
输出配置，子字段见下表。
options
否
object
通用配置，同「文生视频」。
contents 数组元素子字段：
参数名
必选
类型
描述
type
是
string
素材类型。枚举：prompt（文本提示词）/ image（形象参考图）/ video（动作参考视频）/ element（参考主体）。
text
条件必选
string
文本提示词，type=prompt 时必选，不超过 2500 个字符。可通过提示词为画面增加元素、实现运镜效果等；建议不描述动作，动作由参考视频决定。
url
条件必选
string
素材内容，type=image 或 type=video 时必选。图片支持 URL 或 Base64 传入；视频仅支持 URL。
element_id
条件必选
string
元素 ID（由元素管理接口创建），type=element 时必选。仅 kling-video-motion-control-v3.0 支持，最多指定 1 个主体。
id
条件必选
string
素材索引 ID，type=element 时必选，用于在 prompt 中指定；同一任务内不得重复。
素材格式约束：
素材
格式
大小
尺寸
时长
形象参考图（type=image）
.jpg / .jpeg / .png
≤ 50MB
宽高均 ≥ 300px，宽高比 1:2.5 ~ 2.5:1
-
动作参考视频（type=video）
.mp4 / .mov
≤ 100MB
宽高介于 340px ~ 3850px（含）
不短于 3 秒；上限见下方说明
settings 子字段：
子字段
必选
描述
character_orientation
是
生成视频中人物的朝向。枚举：image（与形象参考图中人物一致）/ video（与动作参考视频中人物一致）。
audio
否
是否生成带有声音的视频。枚举：original（保留参考视频原声，默认）/ off（生成的视频不含有声音）。
resolution
否
生成视频的清晰度。枚举：720p（默认）/ 1080p。
注意：
动作参考视频时长上限与 settings.character_orientation 相关：
image（朝向与图片一致）：参考视频最长 10 秒。
video（朝向与视频一致）：参考视频最长 30 秒。
形象参考图内容要求： 图片中人物比例尽量与参考视频中人物比例一致，尽量避免用全身动作驱动半身人物；人物需露出清晰的上半身或全身肢体及头部，避免遮挡；避免倒立、平卧等极端朝向，人物占画面比例不得太低；支持真实 / 风格化角色（人物、类人动物、部分纯动物、部分类人肢体比例的角色）。
动作参考视频内容要求： 建议上传单人动作视频（2 人及以上时取画面占比最大的人物动作）；推荐使用真人动作；动作需一镜到底、角色始终出现在画面中，避免切镜与运镜，否则会被截取；动作过快会显著影响效果。动作难度高或速度快时，可能生成短于上传时长的视频（模型仅提取有效动作时长，最短提取 3 秒可用连续动作即可生成），积分扣减以输出视频时长为准。
接口限制：
引用主体（element）时，生成的视频只能参考视频中的人物朝向。
本接口无 duration 参数，输出时长跟随动作参考视频。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/motion-control' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "kling-video-motion-control-v3.0",
  "contents": [
    {
      "type": "prompt",
      "text": "The girl is wearing a loose gray T-shirt and denim shorts"
    },
    {
      "type": "image",
      "url": "https://example.com/character.png"
    },
    {
      "type": "video",
      "url": "https://example.com/motion.mp4"
    }
  ],
  "settings": {
    "character_orientation": "video",
    "resolution": "1080p"
  }
}'
说明：
引用主体（Element）时，在 contents 中追加一项 {"type": "element", "element_id": "元素ID", "id": "e1"}，仅 kling-video-motion-control-v3.0 支持，最多 1 个。
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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements
2. 输入参数
参数名
必选
类型
描述
element_id
是
string
要删除的元素 ID。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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://example.com/voice-trial.wav",
          "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-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice
2. 输入参数
参数名
必选
类型
描述
voice_id
是
string
要删除的音色 ID（查询接口返回的 voice_id）。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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-intl.tencentcloudmaas.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://example.com/output-video.mp4?q-sign-algorithm=sha1&q-signature=xxxxxx"
        }
      ],
      "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（kling-video-v4 ≤ 30MB）；宽高均 ≥ 300px；宽高比 1:2.5 ~ 2.5:1；支持 URL 或 Base64 传入。kling-video-v4 单任务图片总数 ≤ 10 张。
视频素材约束（kling-video-v4）
项目
约束
格式
.mp4 / .mov
文件大小
≤ 300MB
单段时长
3 ~ 30 秒（含）
总时长
3 ~ 30 秒（含），含参考视频与视频角色主体时长
尺寸
宽高均介于 700px ~ 4553px（含），像素总面积 ≤ 8294400
宽高比
1:2.5 ~ 2.5:1
帧率
24fps ~ 60fps（生成视频帧率为 24fps）
数量
无视频角色主体时最多 5 段；有视频角色主体时，视频角色主体与参考视频合计 ≤ 5 个
传入方式
仅支持公网 URL（http/https）
常见问题
1. 模型如何选择？
单次最长 30 秒、21:9 宽画幅、全能参考最多 15 项素材：kling-video-v4（不支持 audio 与视频编辑）。
能力最全、要 4K / 原生音频 / 多镜头 / 元素：kling-video-v3。
多模态混合输入、视频编辑（参考视频、基础视频改写）：kling-video-v3-omni。
批量生成、速度成本优先：kling-video-v3-turbo（不支持音频与多镜头）。
让人物复刻指定动作：kling-video-motion-control-v3.0（需引用自定义主体时选它）；不需要引用主体时可用上一代 kling-video-motion-control-v2.6。
2. 图生视频能指定画面宽高比吗？
不能。图生视频的输出画幅由输入图片决定，无 aspect_ratio 参数；仅文生视频、全能视频生成支持该参数（全能视频生成在无首帧且无参考视频时必填）。
3. 自定义元素（Element）是什么，怎么用？
元素是基于多张参考图（image_refer）或参考视频（video_refer）创建的定制视觉主体（人物形象等），通过元素管理接口创建后获得 element_id，可在图生视频、全能视频生成中引用，用于跨任务保持角色一致。在提示词中以 @元素名 引用，注意元素名之间避免互为子串。
4. 自定义音色（Voice）是什么，怎么用？
音色是基于参考音频（或含音频的视频）创建的定制声音主体，通过音色管理接口创建后获得 voice_id，可在全能视频生成、数字人（avatar）、对口型（advanced-lip-sync）等接口中引用。查询结果中的 trial_url 为临时试听地址，请及时下载转存。
﻿
﻿

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

模型名称	model 参数值	支持能力	视频时长（秒）	清晰度档位	画面宽高比（文生/全能）	选型建议
Kling-Video-v4	`kling-video-v4`	文生 / 图生（含首尾帧）/ 全能视频生成（参考图、参考视频、主体、音色混合输入）	3 ~ 30	720p / 1080p	21:9、16:9、9:16、1:1；全能另支持 adaptive	新一代旗舰：单次最长 30 秒，支持 21:9 宽画幅，全能视频生成单任务最多组合 15 项参考素材
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-Motion-Control-V3.0	`kling-video-motion-control-v3.0`	动作控制（形象参考图 + 动作参考视频，支持引用主体）	跟随动作参考视频（3 ~ 30s）	720p / 1080p	跟随输入素材	让形象参考图中的人物复刻参考视频的动作；支持引用 1 个主体
Kling-Video-Motion-Control-V2.6	`kling-video-motion-control-v2.6`	动作控制（形象参考图 + 动作参考视频）	跟随动作参考视频（3 ~ 30s）	720p / 1080p	跟随输入素材	动作控制上一代版本，不支持引用主体

参数名	必选	类型	描述
model	是	string	模型版本。取值：`kling-video-v4`、`kling-video-v3`、`kling-video-v3-turbo`
prompt	是	string	提示词，可包含正向与负向描述。v4：纯英文 ≤ 26000 字符，纯非英文 ≤ 11000 字符，中英混合时需满足 `英文字符数 ÷ 26000 + 非英文字符数 ÷ 11000 ≤ 1`；V3：≤ 3072 字符（建议 ≤ 2500），支持多镜头模板语法；V3 Turbo：≤ 2500 字符。
settings	否	object	输出配置，子字段见下表（各模型支持的字段不同）。
options	否	object	通用配置，子字段见下表。

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

字段	类型	说明
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。

素材	格式	大小	尺寸	时长
形象参考图（type=image）	.jpg / .jpeg / .png	≤ 50MB	宽高均 ≥ 300px，宽高比 1:2.5 ~ 2.5:1	-
动作参考视频（type=video）	.mp4 / .mov	≤ 100MB	宽高介于 340px ~ 3850px（含）	不短于 3 秒；上限见下方说明

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	服务内部超时

项目	约束
格式	.mp4 / .mov
文件大小	≤ 300MB
单段时长	3 ~ 30 秒（含）
总时长	3 ~ 30 秒（含），含参考视频与视频角色主体时长
尺寸	宽高均介于 700px ~ 4553px（含），像素总面积 ≤ 8294400
宽高比	1:2.5 ~ 2.5:1
帧率	24fps ~ 60fps（生成视频帧率为 24fps）
数量	无视频角色主体时最多 5 段；有视频角色主体时，视频角色主体与参考视频合计 ≤ 5 个
传入方式	仅支持公网 URL（http/https）

tencent cloud

大模型服务平台 TokenHub

Kling 生视频调用指南

概述

前提条件

调用流程

模型列表

文生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

图生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

全能视频生成（Omni Video）

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

动作控制（Motion Control）

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. 错误码

查询任务结果