Kling
Endpoint: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video认证: Tokenhub API Key / Bearer
Kling 是视频生成模型,支持基于文本和图片的视频生成,以及 Omni 多模态参考生成与视频编辑。同时提供参考角色与声音的管理 API,便于保持角色与音色一致。
基本信息
| 项目 | 值 |
|---|---|
| 调用路径 | Tokenhub API |
| 护栏解除支持 | 不支持 |
各版本支持规格
| 版本 | 分辨率 | 宽高比 | 时长 |
|---|---|---|---|
kling-video-v3 | 720p / 1080p / 4k | 16:9 / 9:16 / 1:1 | 3 ~ 15 秒 |
kling-video-v3-omni | 720p / 1080p / 4k | 16:9 / 9:16 / 1:1 | 3 ~ 15 秒 |
kling-video-v3-turbo | 720p / 1080p | 16:9 / 9:16 / 1:1 | 3 ~ 15 秒 |
输入模式
| 版本 | 输入 |
|---|---|
kling-video-v3 | 文生视频/图生视频(含首尾帧及元素) |
kling-video-v3-omni | Omni 视频生成(文本/图片/视频的多模态输入及视频编辑) |
kling-video-v3-turbo | 文生视频/图生视频 |
调用流程
视频生成是耗时较长的任务,因此 API 采用异步调用方式,分为以下两个步骤。
- 提交任务:调用生成 API(文生视频/图生视频/Omni)。成功后返回
data.id(任务 ID)。 - 轮询结果:直到
data.status = succeeded为止,用任务 ID 调用任务结果查询 API,并从结果中获取视频 URL。
基于文本的视频生成
API 说明
仅使用文本提示词生成视频。V3 支持多镜头模板语法(详情参考"附录:多镜头提示词语法")、原生音频以及 4K 输出。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/text-to-video
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型版本。取值范围:kling-video-v3、kling-video-v3-turbo |
| prompt | 必填 | string | 提示词,可包含正向和负向说明。V3:≤ 3072 字(建议 ≤ 2500),支持多镜头模板语法。V3 Turbo:≤ 2500 字。 |
| settings | 选填 | object | 输出配置。子字段参考下表(支持的字段随模型而异)。 |
| options | 选填 | object | 通用配置。子字段参考下表。 |
settings 子字段(按模型):
| 子字段 | 适用模型 | 说明 |
|---|---|---|
| resolution | 全部 | 分辨率。V3:720p / 1080p / 4k,V3 Turbo:720p / 1080p。默认值:720p。 |
| aspect_ratio | 全部 | 宽高比。可选项:16:9 / 9:16 / 1:1。默认值:16:9。 |
| duration | 全部 | 时长(秒)。3~15 的整数。默认值:5。 |
| multi_shot | 仅 V3 | 是否生成多镜头视频。默认值:true。设置为 false 时,多镜头提示词不会生成多镜头输出。 |
| audio | 仅 V3 | 音频。可选项:native(生成与视频匹配的原生音频)/ off(默认值)。 |
参考: kling-video-v3-turbo 的 settings 仅支持 resolution / aspect_ratio / duration 三个字段,不支持 multi_shot 和 audio。
options 子字段:
| 子字段 | 必填 | 说明 |
|---|---|---|
| external_task_id | 选填 | 账号内唯一的自定义任务 ID,可用该 ID 查询任务。 |
| watermark_info | 选填 | 水印配置。结构:{"enabled": true/false}。为 true 时开启水印。 |
请求示例
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-v3-turbo。V3 Turbo 不支持 audio / multi_shot 字段。
响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| code | int | 业务错误码。0 表示成功,其他值参考附录:统一错误码。 |
| message | string | 错误或提示信息。成功时为 "SUCCEED"。 |
| request_id | string | 系统生成的请求 ID,用于问题追踪和解决。 |
| data | object | 任务数据对象。 |
| data.id | string | 系统生成的任务 ID,用于后续任务查询。 |
| data.status | string | 任务状态。提交成功时固定为 submitted,之后的状态通过查询 API 获取。 |
| data.message | string | 任务状态信息。任务失败时显示失败原因。 |
| data.create_time | long | 任务生成时间。毫秒级 Unix 时间戳。 |
| data.update_time | long | 任务更新时间。毫秒级 Unix 时间戳。 |
响应示例
{
"code": 0,
"message": "SUCCEED",
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"data": {
"id": "task_xxxxxxxxxxxx",
"status": "submitted",
"message": "",
"create_time": 1714000000000,
"update_time": 1714000000000
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。任务提交成功后,生成阶段的任务状态可通过"任务结果查询" API 获取。
| status | 说明 | 处理建议 |
|---|---|---|
| processing | 处理中(含排队) | 继续查询状态。 |
| succeeded | 生成成功 | 使用结果中的视频 URL。 |
| failed | 生成失败 | 确认失败原因并修正后重试。若持续失败,请联系技术支持并提供 request_id。 |
图生视频
API 说明
以图片作为首帧(V3 可选支持尾帧),并结合文本提示词生成视频。V3 还支持元素参考。图片可以通过公开 URL 或 Base64 直接传入,输出宽高比跟随输入图片。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/image-to-video
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型版本。取值范围:kling-video-v3、kling-video-v3-turbo |
| contents | 必填 | array | 参考素材集合。同一素材的字段放在同一个对象中。必须分别至少包含一个 prompt 和 first_frame。子字段参考下表。 |
| settings | 选填 | object | 输出配置。子字段参考下表。参考:图生视频没有 aspect_ratio 参数,宽高比由输入图片决定。 |
| options | 选填 | object | 通用配置,与文生视频相同。 |
contents 数组元素的子字段:
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| type | 必填 | string | 素材类型。各模型支持范围:V3:prompt / first_frame / last_frame / element,V3 Turbo:prompt / first_frame。 |
| text | 条件必填 | string | 文本提示词。type=prompt 时必填。≤ 2500 字。V3 支持多镜头模板语法和 @element 参考。 |
| url | 条件必填 | string | 图片资产(URL 或 Base64)。type=first_frame / last_frame 时必填。限制条件:.jpg/.jpeg/.png,≤ 50 MB,宽度和高度均 ≥ 300 px,宽高比 1:2.5~2.5:1。 |
| element_id | 条件必填 | string | 元素参考(JSON 定义)。type=element 时必填,且仅 V3 支持。最大 3 个,在提示词中用 @xxx 参考。 |
settings 子字段(按模型):
| 子字段 | 适用模型 | 说明 |
|---|---|---|
| resolution | 全部 | 分辨率。V3:720p / 1080p / 4k,V3 Turbo:720p / 1080p。默认值:720p。 |
| duration | 全部 | 时长(秒)。3~15 的整数。默认值:5。 |
| multi_shot | 仅 V3 | 是否生成多镜头视频。默认值:true。 |
| audio | 仅 V3 | 音频。可选项:native / off(默认值:off)。 |
参考: 首帧和尾帧仅支持"仅首帧"和"首帧 + 尾帧",不支持"仅尾帧"。请不要使用互为子字符串关系的元素名称(例如 @Zhang 和 @ZhangSan)。
请求示例
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": "Make the subject in the image turn its head naturally while the camera slowly zooms in"
},
{
"type": "first_frame",
"url": "https://example.com/start.jpg"
}
],
"settings": {
"resolution": "1080p",
"duration": 5
}
}'响应参数
与"文生视频"的输出参数相同。
响应示例
{
"code": 0,
"message": "SUCCEED",
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"data": {
"id": "task_xxxxxxxxxxxx",
"status": "submitted",
"message": "",
"create_time": 1714000000000,
"update_time": 1714000000000
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。任务状态说明与"文生视频"相同。
Omni 视频生成
API 说明
V3 Omni 的统一多模态生成入口。可以综合使用提示词、参考图片(首/尾帧、参考图片)、参考视频(特征视频/待编辑的基础视频)以及元素来生成或编辑视频。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/omni-video
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| model | 必填 | string | 模型版本。取值: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(音色)。 |
| text | 条件必填 | string | 文本提示词。type=prompt 时必填。≤ 3072 字(建议 ≤ 2500)。支持 @xxx 素材参考和多镜头语法,并可通过 @id 参考声音素材。 |
| url | 条件必填 | string | 图片/视频资产。图片支持 URL 或 Base64,视频仅支持 URL。图片限制条件:jpg/jpeg/png,≤ 50 MB,宽度和高度 ≥ 300 px,宽高比 1:2.5~2.5:1。视频限制条件:mp4/mov,≤ 200 MB,时长 3~15.5 秒。 |
| element_id | 条件必填 | string | 元素 ID(通过元素管理 API 生成)。type=element 时必填。 |
| voice_id | 条件必填 | string | 声音 ID。type=voice 时必填。在"声音管理"中生成后查询获取,或使用系统预置声音。 |
| id | 条件必填 | string | 素材索引 ID。type=voice 时必填,且在同一任务内必须唯一。要使用该声音,请在提示词中用 @id 参考。 |
settings 子字段:
| 子字段 | 必填 | 说明 |
|---|---|---|
| resolution | 选填 | 分辨率。720p / 1080p / 4k。默认值:720p。 |
| aspect_ratio | 条件必填 | 宽高比:16:9 / 9:16 / 1:1,默认值 16:9。首帧和参考视频均没有时必填。 |
| duration | 选填 | 时长(秒)。3~15 的整数。默认值:5。 |
| multi_shot | 选填 | 是否生成多镜头视频。默认值:true。 |
| audio | 选填 | 音频。可选项:native / original / off(默认值:off)。original=保留参考视频的原始音频。 |
**参考:**输入组合限制: 首帧和尾帧仅支持"仅首帧"和"首帧 + 尾帧"。参考视频最多只能提供 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),且不支持多镜头。
请求示例
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://mpstestmodel-1315536146.cos.ap-singapore.myqcloud.com/justin/wiki-examples/vega-pro-example.mp4"
}
],
"settings": {
"resolution": "1080p",
"duration": 5,
"audio": "original"
}
}'响应参数
与"文生视频"的输出参数相同。
响应示例
{
"code": 0,
"message": "SUCCEED",
"request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
"data": {
"id": "task_xxxxxxxxxxxx",
"status": "submitted",
"message": "",
"create_time": 1714000000000,
"update_time": 1714000000000
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。任务状态说明与"文生视频"相同。
元素管理
元素管理用于生成、查询和删除自定义参考对象(自定义角色)。可以基于多张参考图片(image_refer)或参考视频(video_refer)生成参考对象。生成后,可在图生视频和 Omni 视频生成 API 中以 element_id 参考,从而复用自定义角色。
生成参考对象
API 说明
生成自定义参考对象。生成是异步任务。提交后请通过"参考对象查询" API 轮询任务状态。成功后获取 element_id。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| 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, 10 MB 以下,宽度和高度均 300 px 以上,宽高比 1:2.5~2.5:1。 |
| element_video_list | 条件必填 | object | 视频参考对象,reference_type=video_refer 时必填。结构:{"refer_videos": [{"video_url": "..."}]}。限制条件:MP4/MOV,时长 3~8 秒,1080P,宽高比 16:9 或 9:16,200 MB 以下。 |
| 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。 |
请求示例
多图参考对象(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": "A young man with short hair, wearing a blue jacket",
"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": "A young man with short hair, wearing a blue jacket",
"reference_type": "video_refer",
"element_video_list": {
"refer_videos": [
{
"video_url": "https://example.com/demo.mp4"
}
]
}
}'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 | 配额扣除的原价。 |
响应示例
{
"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
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。
参考对象查询
API 说明
查询参考对象生成任务的状态和结果。提交生成任务并收到任务 ID 后,直到 data.task_status = succeed 为止轮询该 API,并从 data.task_result.elements 获取参考对象信息。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/{id}
参考: 路径中的 {id} 是任务生成时返回的 data.task_id,也可以用生成时传入的 external_task_id 替代。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 元素生成任务的任务 ID,填入查询路径的 {id}。或者可以用生成时使用的 external_task_id 替代。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 | 配额扣除的原价。 |
响应示例
{
"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": "Advanced Subject_Image Test",
"element_description": "A young man with short hair, wearing a blue jacket",
"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"
}
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。任务失败原因参考 data.task_status_msg。
删除参考对象
API 说明
删除自定义参考对象。仅可删除自定义元素,官方元素(owned_by=kling)不可删除。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-advanced-elements
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| element_id | 必填 | string | 要删除的元素 ID。 |
请求示例
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"
}'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 时间戳。 |
响应示例
{
"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"
}
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。
声音管理
声音管理用于生成、查询和删除自定义声音。基于参考音频(或包含音频的视频)生成声音。生成后,可在 Omni 视频生成(contents 中 type=voice 的素材)、数字人(avatar)、唇形同步(advanced-lip-sync)等 API 中以 voice_id 参考。
声音生成是异步任务,分为以下两个步骤。
- 提交任务:调用生成 API。成功后返回
data.task_id(任务 ID)。 - 轮询结果:直到
data.task_status = succeed为止,用任务 ID 调用声音任务查询 API,并从data.task_result.voices获取voice_id。
生成声音
API 说明
基于参考音频(或包含音频的视频)生成自定义声音。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| voice_name | 必填 | string | 声音名称。 |
| voice_url | 条件必填 | string | 参考音频的公开 URL。该参数与 video_id 二选一。 |
| video_id | 条件必填 | string | 包含目标音频的视频的视频 ID(视频生成任务中生成的视频)。该参数与 voice_url 二选一。 |
| external_task_id | 选填 | string | 账号内唯一的自定义任务 ID。 |
请求示例
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": "Test voice",
"voice_url": "https://example.com/reference.mp3"
}'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 时间戳。 |
响应示例
{
"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
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。
声音任务查询
API 说明
用生成 API 返回的任务 ID 轮询声音生成任务。任务成功后,从结果中获取 voice_id 和预览 URL。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/{task_id}
参考: 路径中的 {task_id} 是生成 API 返回的 data.task_id。也可以用生成时传入的 external_task_id 替代。建议每 2~3 秒 轮询一次。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 任务 ID(路径参数),是生成 API 返回的 data.task_id。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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,用于在数字人和唇形同步等 API 中参考。 |
| data.task_result.voices[].voice_name | string | 声音名称。 |
| data.task_result.voices[].trial_url | string | 声音预览音频 URL 是临时 URL。请立即下载保存。 |
| 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 | 配额扣除的原价。 |
响应示例
{
"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": "Test voice",
"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"
}
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。任务失败原因参考 data.task_status_msg。
删除声音
API 说明
删除指定的自定义声音。仅可删除自定义声音。删除后,在生成 API 中将无法再参考该声音。
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/delete-voice
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| voice_id | 必填 | string | 要删除的声音 ID(查询 API 返回的 voice_id)。 |
请求示例
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"
}'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 时间戳。 |
响应示例
{
"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"
}
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。
任务结果查询
API 说明
所有生成 API(文生视频/图生视频/统一型)共用的任务查询方式。提交任务并返回任务 ID 后,通过统一任务查询端点轮询任务状态。成功后从结果中获取视频 URL。
API: GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/{task_id}
参考: 路径中的 {task_id} 是提交任务时返回的 data.id。视频生成大约需要几分钟,因此建议每 3~5 秒 轮询一次。响应字段依照官方 Kling API 结构提供,实际返回的响应优先。
请求参数
| 参数 | 必填 | 类型 | 说明 |
|---|---|---|---|
| task_id | 必填 | string | 任务 ID(路径参数),是提交任务时返回的 data.id。 |
请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/YOUR_TASK_ID' \
-H 'Authorization: Bearer YOUR_API_KEY'响应参数
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 | 视频文件 URL 是临时 URL。请立即下载保存。 |
| data[].outputs[].duration | string | 视频时长(秒)。 |
| data[].create_time | long | 任务生成时间。毫秒级 Unix 时间戳。 |
| data[].update_time | long | 任务更新时间。毫秒级 Unix 时间戳。 |
| tokenhub_usage | object | 使用量。 |
| tokenhub_usage.total_tokens | integer | 该任务消耗的 token 数,用于计费/结算。 |
响应示例
{
"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
}
}错误码
请求失败时,code 不是 0。具体的错误码和处理建议参考"附录:统一错误码"。任务状态说明与"文生视频"相同。
附录
统一错误码
| HTTP 状态码 | 业务码 | 错误消息 | 说明 |
|---|---|---|---|
200 | 0 | success | 请求成功 |
401 | 1000 | 认证失败 | 没有 Authorization 或 apikey 无效。 |
401 | 1001 | Authorization 为空 | 未包含 Authorization 头。 |
401 | 1002 | Authorization 无效 | apikey 无效或已过期。 |
401 | 1003 | Authorization 尚未生效 | apikey 尚未生效。 |
401 | 1004 | Authorization 已过期 | apikey 已过期。 |
429 | 1100 | 账号异常 | 账号异常(可能欠费、停用或封禁) |
429 | 1101 | 账号欠费(后付费) | 后付费账号已欠费。 |
429 | 1102 | 资源包耗尽或过期 | 资源包已用完或已过期。 |
403 | 1103 | 拒绝访问所请求的资源 | 无法访问所请求的资源(未订阅相应模型/功能)。 |
400 | 1200 | 请求参数有误 | 请求参数有误(缺少必填字段、类型错误、枚举值超出范围等)。 |
400 | 1201 | 参数有误 | 参数值有误。请在文档中确认有效的取值范围。 |
404 | 1202 | 请求的方法无效 | HTTP 方法有误。 |
404 | 1203 | 请求的资源不存在 | 端点路径有误或资源不存在。 |
400 | 1300 | 触发平台策略 | 触发了平台策略(内容审核不通过或输入不合规等)。 |
400 | 1301 | 触发平台敏感词列表 | 检测到敏感词或不合规的提示词。 |
429 | 1302 | API 调用过于频繁 | 调用频率过高,已触发限速。 |
429 | 1303 | 超出并发或 QPS 限制 | 并发或 QPS 超出了预置配额。 |
400 | 1304 | 触发 IP 策略 | 触发了基于 IP 地址策略的拦截。 |
500 | 5000 | 服务器内部错误 | 服务器内部错误 |
503 | 5001 | 服务器暂时不可用 | 服务暂时不可用(通常因为高负载或维护)。 |
504 | 5002 | 服务器内部超时 | 服务器内部超时 |
多镜头提示词语法
- 格式:
shot n, m, words; shot n, m, words;。各镜头请用半角分号分隔。 n:镜头编号。最少支持1 个、最多支持6个镜头。m:镜头时长(秒)。每个镜头至少需为1 秒,且所有镜头时长之和必须等于整个视频时长。words:该镜头的提示词。最大长度:512字。- 整个提示词的最大长度为
3072字(建议2500字以下)。同时支持正向和负向说明。 - 仅
kling-video-v3和kling-video-v3-omni支持该功能,且需要multi_shot=true(默认值)才会生效。
图片资产的通用限制条件
格式:.jpg / .jpeg / .png(不支持透明通道)。文件大小:50 MB 以下。宽度和高度:各自最少 300 px。宽高比:1:2.5~2.5:1。支持 URL 或 Base64 输入。
FAQ
1. 三个模型中应该选择哪一个?
- 功能最全面的选项,包含
4K/ 原生音频 / 多镜头 / 元素支持:kling-video-v3。 - 多模态混合输入及视频编辑(参考视频、基础视频改写):
kling-video-v3-omni。 - 优先考虑速度和成本的批量生成:
kling-video-v3-turbo(不支持音频和多镜头)。
2. 图生视频可以指定宽高比吗?
不可以。图生视频的输出宽高比由输入图片决定,无法使用 aspect_ratio 参数。仅文生视频和 Omni 视频生成支持该参数;在 Omni 视频生成中,首帧和参考视频均没有时该参数为必填。
3. 什么是自定义元素,如何使用?
元素是用多张参考图片(image_refer)或参考视频(video_refer)生成的自定义视觉参考对象(例如角色)。通过元素管理 API 生成后可获取 element_id,并在图生视频和 Omni 视频生成中参考,从而在不同任务间保持角色一致性。在提示词中用 @ElementName 参考元素,并且不要使用互为子字符串关系的元素名称。
4. 什么是自定义声音,如何使用?
声音是用参考音频(或包含音频的视频)生成的自定义声音参考对象。通过声音管理 API 生成后可获取 voice_id,并可在 Omni 视频生成、数字人(avatar)、唇形同步(advanced-lip-sync)等 API 中参考。查询结果中的 trial_url 是临时预览 URL,请立即下载保存。