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

一、概述

这篇说说如何通过 TokenHub 调用可灵的九款模型：kling-video-v4、kling-video-v2.5-turbo、kling-video-v2.6、kling-video-v3-turbo、kling-video-v3、kling-video-v3-omni、kling-video-o1、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，从结果中获取视频地址。

四、模型列表

注意：说明：

注意：「画面宽高比」列为文生视频、全能视频生成支持的取值范围；图生视频、首尾帧生视频无 aspect_ratio 参数，输出画幅跟随输入图片比例；动作控制同样无 aspect_ratio 参数，输出画幅跟随输入素材。kling-video-v4 全能视频生成的 aspect_ratio 默认为 adaptive，由模型根据输入素材自动选择画幅。

六、1. 接口描述

仅凭文本提示词生成视频。v4 单次最长 30 秒，支持 21:9 宽画幅；V3 支持多镜头模板语法，详情请参见 附录：多镜头提示词语法、原生音频与 4K 输出。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/text-to-video

七、2. 输入参数

settings 子字段（按模型）：

注意：说明：

注意：kling-video-v4、kling-video-v3-turbo、kling-video-v2.5-turbo 的 settings 仅支持 resolution / aspect_ratio / duration 三个字段，不支持 multi_shot 与 audio。

options 子字段：

八、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-v4", "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 }}'

注意：说明：

注意：将示例中的 model 替换为 kling-video-v3、kling-video-v3-turbo、kling-video-v2.6 或 kling-video-v2.5-turbo，即可调用对应模型（注意各模型 settings 字段差异，v4、V3 Turbo 与 V2.5 Turbo 不支持 audio / multi_shot，调用时需删去 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，具体错误码及处理建议见 附录：统一错误码。任务提交成功后，生成阶段的任务状态通过 查询任务结果 接口获取：

十三、1. 接口描述

以图片为首帧（v4 /V3 / V2.6 / V2.5 Turbo 可选尾帧）结合文本提示词生成视频。V3 额外支持元素引用（Element）。图片直接传入公网 URL 或 Base64，输出画幅跟随输入图片。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/image-to-video

十四、2. 输入参数

contents 数组元素子字段：

settings 子字段（按模型）：

十五、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 }}'

注意：说明：

注意：将示例中的 model 替换为 kling-video-v4、kling-video-v3-turbo、kling-video-v2.6 或 kling-video-v2.5-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，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。

20、1. 接口描述

v4 / V3 Omni / O1 的多模态统一生成入口：可综合使用提示词、参考图片（首/尾帧、参考图）、参考视频（特征视频 / 待编辑基础视频）、元素（Element）与音色（Voice）生成或编辑视频。v4 不支持待编辑基础视频（base_video），即不支持视频编辑。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/omni-video

21、2. 输入参数

contents 数组元素子字段：

settings 子字段：

注意：Kling-Video-v4 不支持 audio 参数。 v4 的 settings 仅支持 resolution / aspect_ratio / duration；如需指定音色，请在 contents 中使用 {"type": "voice", "voice_id": "音色ID", "id": "1"}，无需（也不支持）传 settings.audio。

注意：v4 输入组合限制：

注意：V3 Omni / O1 输入组合限制：

22、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 参数）。

v4 请求示例（参考图 + 特征参考视频）：

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-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.tencentmaas.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 }}'

注意：说明：

23、4. 输出参数

同「文生视频」输出参数。

24、5. 响应示例

{ "code": 0, "message": "SUCCEED", "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "data": { "id": "task_xxxxxxxxxxxx", "status": "submitted", "message": "", "create_time": 1714000000000, "update_time": 1714000000000 }}

25、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。

27、1. 接口描述

用一段「动作参考视频」驱动「形象参考图」中的人物，生成动作与参考视频一致的视频；V3.0 还可通过元素（Element）直接指定定制角色。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/motion-control

28、2. 输入参数

contents 数组元素子字段：

素材格式约束：

settings 子字段：

注意：动作参考视频时长上限与 settings.character_orientation 相关：

注意：形象参考图内容要求： 图片中人物比例尽量与参考视频中人物比例一致，尽量避免用全身动作驱动半身人物；人物需露出清晰的上半身或全身肢体及头部，避免遮挡；避免倒立、平卧等极端朝向，人物占画面比例不得太低；支持真实 / 风格化角色（人物、类人动物、部分纯动物、部分类人肢体比例的角色）。

注意：动作参考视频内容要求： 建议上传单人动作视频（2 人及以上时取画面占比最大的人物动作）；推荐使用真人动作；动作需一镜到底、角色始终出现在画面中，避免切镜与运镜，否则会被截取；动作过快会显著影响效果。动作难度高或速度快时，可能生成短于上传时长的视频（模型仅提取有效动作时长，最短提取 3 秒可用连续动作即可生成），积分扣减以输出视频时长为准。

注意：接口限制：

29、3. 请求示例

curl -X POST 'https://tokenhub.tencentmaas.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 个。

30、4. 输出参数

同「文生视频」输出参数。

31、5. 响应示例

{ "code": 0, "message": "SUCCEED", "request_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", "data": { "id": "task_xxxxxxxxxxxx", "status": "submitted", "message": "", "create_time": 1714000000000, "update_time": 1714000000000 }}

32、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。

33、元素管理（Element）

元素管理用于创建、查询与删除自定义主体（定制角色）。主体可基于多张参考图（image_refer）或参考视频（video_refer）创建，创建后可在图生视频、全能视频生成接口中通过 element_id 引用，实现定制角色的复用。

35、1. 接口描述

创建自定义主体。创建为异步任务，提交后通过「查询主体」接口轮询任务状态，成功后获得 element_id。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/advanced-custom-elements

36、2. 输入参数

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

38、4. 输出参数

39、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 }}

40、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。

42、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 替代

43、2. 输入参数

44、3. 请求示例

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

45、4. 输出参数

46、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" } }}

47、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务失败原因见 data.task_status_msg。

49、1. 接口描述

删除自定义主体。仅支持删除自定义元素，元素（owned_by=kling）不可删除。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/delete-advanced-elements

50、2. 输入参数

51、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"}'

52、4. 输出参数

53、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" } }}

54、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。

55、音色管理（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。

57、1. 接口描述

基于参考音频（或含音频的视频）创建自定义音色。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/custom-voices

58、2. 输入参数

59、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"}'

60、4. 输出参数

61、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 }}

62、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。

64、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 秒轮询一次。

65、2. 输入参数

66、3. 请求示例

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

67、4. 输出参数

68、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" } }}

69、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务失败原因见 data.task_status_msg。

71、1. 接口描述

删除指定的自定义音色，仅支持删除自定义音色。删除后该音色不可再在生成接口中引用。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/kling/delete-voice

72、2. 输入参数

73、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"}'

74、4. 输出参数

75、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" } }}

76、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。

78、1. 接口描述

各生成接口（文生/图生/全能）共用的任务查询方式：提交任务返回任务 ID 后，通过统一的任务查询端点轮询任务状态，成功后从结果中获取视频地址。

接口： GET https://tokenhub.tencentmaas.com/v1/wand/kling/tasks/{task_id}

注意：说明：

注意：路径中的 {task_id} 即提交任务时返回的 data.id（示例中以 YOUR_TASK_ID 占位）。视频生成约需数分钟，建议每 3~5 秒轮询一次。响应字段按可灵 API 结构给出，以实际返回为准。

79、2. 输入参数

80、3. 请求示例

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

81、4. 输出参数

82、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 }}

83、6. 错误码

请求失败时 code 不为 0，具体错误码及处理建议见 附录：统一错误码。任务状态说明同「文生视频」。

85、统一错误码

86、多镜头（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（默认）方可生效。

87、图片素材通用约束

格式 .jpg / .jpeg / .png（不支持透明通道）；文件 ≤ 50MB（kling-video-v4 ≤ 30MB）；宽高均 ≥ 300px；宽高比 1:2.5 ~ 2.5:1；支持 URL 或 Base64 传入。kling-video-v4 单任务图片总数 ≤ 10 张。

88、视频素材约束（kling-video-v4）

90、1. 九款模型如何选择？

·单次最长 30 秒、21:9 宽画幅、全能参考最多 15 项素材：kling-video-v4（不支持 audio 与视频编辑）。

·能力最全、要 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。

·让人物复刻指定动作：kling-video-motion-control-v3.0（需引用自定义主体时选它）；不需要引用主体时可用上一代 kling-video-motion-control-v2.6。

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

不能。图生视频的输出画幅由输入图片决定，无 aspect_ratio 参数；仅文生视频、全能视频生成支持该参数（全能视频生成在无首帧且无参考视频时必填）。

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

元素是基于多张参考图（image_refer）或参考视频（video_refer）创建的定制视觉主体（人物形象等），通过元素管理接口创建后获得 element_id，可在图生视频、全能视频生成中引用，用于跨任务保持角色一致。在提示词中以 @元素名 引用，注意元素名之间避免互为子串。

93、4. 自定义音色（Voice）是什么，怎么用？

音色是基于参考音频（或含音频的视频）创建的定制声音主体，通过音色管理接口创建后获得 voice_id，可在数字人（avatar）、对口型（advanced-lip-sync）等接口中引用。查询结果中的 trial_url 为临时试听地址，请及时下载转存。