跳到内容

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-v3720p / 1080p / 4k16:9 / 9:16 / 1:13 ~ 15 秒
kling-video-v3-omni720p / 1080p / 4k16:9 / 9:16 / 1:13 ~ 15 秒
kling-video-v3-turbo720p / 1080p16:9 / 9:16 / 1:13 ~ 15 秒

输入模式 ​

版本输入
kling-video-v3文生视频/图生视频(含首尾帧及元素)
kling-video-v3-omniOmni 视频生成(文本/图片/视频的多模态输入及视频编辑)
kling-video-v3-turbo文生视频/图生视频

调用流程 ​

视频生成是耗时较长的任务,因此 API 采用异步调用方式,分为以下两个步骤。

  1. 提交任务:调用生成 API(文生视频/图生视频/Omni)。成功后返回 data.id(任务 ID)。
  2. 轮询结果:直到 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 时开启水印。

请求示例 ​

bash
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 字段。

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功,其他值参考附录:统一错误码。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring系统生成的请求 ID,用于问题追踪和解决。
dataobject任务数据对象。
data.idstring系统生成的任务 ID,用于后续任务查询。
data.statusstring任务状态。提交成功时固定为 submitted,之后的状态通过查询 API 获取。
data.messagestring任务状态信息。任务失败时显示失败原因。
data.create_timelong任务生成时间。毫秒级 Unix 时间戳。
data.update_timelong任务更新时间。毫秒级 Unix 时间戳。

响应示例 ​

json
{
  "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)。

请求示例 ​

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

响应参数 ​

与"文生视频"的输出参数相同。

响应示例 ​

json
{
  "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),且不支持多镜头。

请求示例 ​

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

响应参数 ​

与"文生视频"的输出参数相同。

响应示例 ​

json
{
  "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):

bash
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):

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

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring系统生成的请求 ID,用于问题追踪和解决。
data.task_idstring系统生成的任务 ID。
data.task_statusstring任务状态:submitted / processing / succeed / failed。
data.task_info.external_task_idstring自定义任务 ID(生成时提供过则返回)。
data.task_status_msgstring任务失败时显示失败原因,正常时为空字符串。
data.created_atnumber任务生成时间。毫秒级 Unix 时间戳。
data.updated_atnumber任务最后更新时间。毫秒级 Unix 时间戳。
data.final_unit_deductionstring任务最终扣除的点数值。
data.final_balance_deduction.quotastring配额扣除的折扣价。
data.final_balance_deduction.list_pricestring配额扣除的原价。

响应示例 ​

json
{
  "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 替代。

请求示例 ​

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/advanced-custom-elements/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring系统生成的请求 ID,用于问题追踪和解决。
data.task_idstring系统生成的任务 ID。
data.task_statusstring任务状态:submitted / processing / succeed / failed。
data.task_info.external_task_idstring自定义任务 ID(生成时提供过则返回)。
data.task_status_msgstring任务失败时显示失败原因,正常时为空字符串。
data.task_result.elements[]array参考对象列表。task_status=succeed 时返回。
data.task_result.elements[].element_idnumber全局唯一的参考对象 ID。
data.task_result.elements[].element_namestring参考对象名称。
data.task_result.elements[].element_descriptionstring参考对象说明。
data.task_result.elements[].element_typestring参考方式:image_refer(多图参考对象)/ video_refer(视频参考对象)。
data.task_result.elements[].element_image_listobject图片参考信息(image_refer 时可用)。包含 frontal_image 及 refer_images[].image_url。
data.task_result.elements[].element_video_listobject视频参考信息(video_refer 时可用)。
data.task_result.elements[].owned_bystring参考对象来源。kling 表示官方参考对象库,其他值表示生成者 ID。
data.task_result.elements[].statusstring参考对象状态:succeed(正常)/ deleted。
data.created_atnumber任务生成时间。毫秒级 Unix 时间戳。
data.updated_atnumber任务最后更新时间。毫秒级 Unix 时间戳。
data.final_unit_deductionstring任务最终扣除的点数值。
data.final_balance_deduction.quotastring配额扣除的折扣价。
data.final_balance_deduction.list_pricestring配额扣除的原价。

响应示例 ​

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

请求示例 ​

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

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring系统生成的请求 ID,用于问题追踪和解决。
data.task_idstring系统生成的任务 ID。
data.task_statusstring任务状态:submitted / processing / succeed / failed。
data.task_status_msgstring任务失败时显示失败原因,正常时为空字符串。
data.created_atnumber任务生成时间。毫秒级 Unix 时间戳。
data.updated_atnumber任务最后更新时间。毫秒级 Unix 时间戳。

响应示例 ​

json
{
  "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 参考。

声音生成是异步任务,分为以下两个步骤。

  1. 提交任务:调用生成 API。成功后返回 data.task_id(任务 ID)。
  2. 轮询结果:直到 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。

请求示例 ​

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

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring系统生成的请求 ID,用于问题追踪和解决。
data.task_idstring系统生成的任务 ID,用于后续任务查询。
data.task_statusstring任务状态:submitted / processing / succeed / failed。
data.task_info.external_task_idstring自定义任务 ID(生成时提供过则返回)。
data.created_atnumber任务生成时间。毫秒级 Unix 时间戳。
data.updated_atnumber任务最后更新时间。毫秒级 Unix 时间戳。

响应示例 ​

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

请求示例 ​

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/custom-voices/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring请求 ID。
data.task_idstring任务 ID。
data.task_statusstring任务状态:submitted / processing / succeed / failed。
data.task_status_msgstring任务状态信息。任务失败时显示失败原因。
data.task_info.external_task_idstring自定义任务 ID(生成时提供过则返回)。
data.task_result.voices[]array声音列表。task_status=succeed 时返回。
data.task_result.voices[].voice_idstring声音 ID,用于在数字人和唇形同步等 API 中参考。
data.task_result.voices[].voice_namestring声音名称。
data.task_result.voices[].trial_urlstring声音预览音频 URL 是临时 URL。请立即下载保存。
data.task_result.voices[].owned_bystring声音所有者标识。
data.task_result.voices[].statusstring声音状态:succeed(正常)/ deleted。
data.created_atnumber任务生成时间。毫秒级 Unix 时间戳。
data.updated_atnumber任务最后更新时间。毫秒级 Unix 时间戳。
data.final_unit_deductionstring该任务扣除的单位数。
data.final_balance_deduction.quotastring配额扣除的折扣价。
data.final_balance_deduction.list_pricestring配额扣除的原价。

响应示例 ​

json
{
  "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)。

请求示例 ​

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

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。成功时为 "SUCCEED"。
request_idstring请求 ID。
data.task_idstring声音对应的生成任务 ID。
data.task_statusstring任务状态:submitted / processing / succeed / failed。
data.task_resultobject删除结果对象(通常为空对象 {},表示删除成功)。
data.task_status_msgstring任务失败时显示失败原因,正常时为空字符串。
data.created_atnumber任务生成时间。毫秒级 Unix 时间戳。
data.updated_atnumber任务最后更新时间。毫秒级 Unix 时间戳。

响应示例 ​

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

请求示例 ​

bash
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/kling/tasks/YOUR_TASK_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY'

响应参数 ​

字段类型说明
codeint业务错误码。0 表示成功。
messagestring错误或提示信息。
request_idstring请求 ID。
dataarray任务结果列表。
data[].idstring任务 ID。
data[].statusstring任务状态:processing / succeeded / failed。
data[].messagestring任务状态信息。任务失败时显示失败原因。
data[].outputsarray视频结果列表。
data[].outputs[].typestring生成结果类型。当前视频结果为 video。
data[].outputs[].idstring视频 ID。
data[].outputs[].urlstring视频文件 URL 是临时 URL。请立即下载保存。
data[].outputs[].durationstring视频时长(秒)。
data[].create_timelong任务生成时间。毫秒级 Unix 时间戳。
data[].update_timelong任务更新时间。毫秒级 Unix 时间戳。
tokenhub_usageobject使用量。
tokenhub_usage.total_tokensinteger该任务消耗的 token 数,用于计费/结算。

响应示例 ​

json
{
  "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 状态码业务码错误消息说明
2000success请求成功
4011000认证失败没有 Authorization 或 apikey 无效。
4011001Authorization 为空未包含 Authorization 头。
4011002Authorization 无效apikey 无效或已过期。
4011003Authorization 尚未生效apikey 尚未生效。
4011004Authorization 已过期apikey 已过期。
4291100账号异常账号异常(可能欠费、停用或封禁)
4291101账号欠费(后付费)后付费账号已欠费。
4291102资源包耗尽或过期资源包已用完或已过期。
4031103拒绝访问所请求的资源无法访问所请求的资源(未订阅相应模型/功能)。
4001200请求参数有误请求参数有误(缺少必填字段、类型错误、枚举值超出范围等)。
4001201参数有误参数值有误。请在文档中确认有效的取值范围。
4041202请求的方法无效HTTP 方法有误。
4041203请求的资源不存在端点路径有误或资源不存在。
4001300触发平台策略触发了平台策略(内容审核不通过或输入不合规等)。
4001301触发平台敏感词列表检测到敏感词或不合规的提示词。
4291302API 调用过于频繁调用频率过高,已触发限速。
4291303超出并发或 QPS 限制并发或 QPS 超出了预置配额。
4001304触发 IP 策略触发了基于 IP 地址策略的拦截。
5005000服务器内部错误服务器内部错误
5035001服务器暂时不可用服务暂时不可用(通常因为高负载或维护)。
5045002服务器内部超时服务器内部超时

多镜头提示词语法 ​

  • 格式: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,请立即下载保存。

基于 VitePress 构建 · 部署于腾讯云 EdgeOne Pages