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

二、前提条件

·已 注册腾讯云 账号并开通 TokenHub 服务。

·已在 TokenHub 控制台 获取 API Key。

·在 控制台-在线推理-视觉模型 处开启对应模型的后付费。

注意：说明：

注意：下文所有示例中的 YOUR_API_KEY 均需替换为你自己的 API Key，鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY。

三、调用流程

视频生成为耗时任务，接口采用异步调用模式，统一分两步：

1. 提交任务：调用生成接口，成功返回 task_id 与初始状态 created。

2. 轮询结果：携带 task_id 调用「查询任务结果」接口，直至 state = success，从结果中获取视频地址。

注意：任务状态：created（创建成功）/ queueing（排队中）/ processing（处理中）/ success（成功）/ failed（失败）。所有接口响应均包含 request_id（顶层，用于排查问题）；查询接口额外返回 tokenhub_usage（用量消耗）。

四、模型列表

注意：说明：

六、1. 接口描述

通过纯文本提示词创建文生视频任务，可指定时长、比例、分辨率、运动幅度、音视频直出与 BGM 等参数。

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

七、2. 输入参数

八、3. 请求示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vidu/text-to-video' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "vidu-video-q2", "prompt": "一只橙色小猫在窗台上看向镜头"}'

注意：说明：

注意：将示例中的 model 替换为 vidu-video-q3-turbo 或 vidu-video-q3-pro，即可调用对应模型；duration / aspect_ratio / resolution / audio 等参数详见 输入参数。

九、4. 输出参数

十、5. 响应示例

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "state": "created", "model": "vidu-video-q3-turbo", "prompt": "一只小猫在月光下奔跑，镜头跟随", "duration": 5, "aspect_ratio": "16:9", "resolution": "720p", "audio": true, "seed": 0, "credits": 100, "created_at": "2026-07-31T15:41:31.968Z", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

十一、6. 错误码

请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。

十三、1. 接口描述

以一张首帧图像为起点生成视频，可选文本提示词、音视频直出、指定音色与推荐提示词等。输出画幅跟随输入图片比例（无 aspect_ratio 参数）。

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

十四、2. 输入参数

十五、3. 请求示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vidu/image-to-video' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "vidu-video-q3-turbo", "images": ["https://example.com/start.jpg"], "prompt": "让画面中的主体自然运动，镜头缓慢推近", "duration": 5, "resolution": "720p", "audio": true}'

十六、4. 输出参数

十七、5. 响应示例

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "state": "created", "model": "vidu-video-q3-turbo", "prompt": "让画面中的主体自然运动，镜头缓慢推近", "images": ["https://example.com/start.jpg"], "duration": 5, "audio": true, "seed": 0, "resolution": "720p", "credits": 100, "created_at": "2026-07-31T15:41:31.968Z", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

十八、6. 错误码

请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。

20、1. 接口描述

以参考素材（图片/视频/主体）保持主体一致性生成视频，支持两种调用方式：方式一使用 subjects 主体（可在 prompt 中以 @主体名 引用）；方式二直接使用顶层 images/videos 参考。两者必选其一。

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

21、2. 输入参数

subjects 数组元素子字段：

注意：说明：

注意：主体数量限制：

22、3. 请求示例

方式一：subjects 主体

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vidu/reference-to-video' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "vidu-video-q3-turbo", "subjects": [ { "name": "girl", "images": ["https://example.com/girl1.jpg"] }, { "name": "boy", "images": ["https://example.com/boy1.jpg"] } ], "prompt": "@girl 和 @boy 在一起吃火锅", "duration": 8, "audio": true}'

方式二：直接 images 参考

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vidu/reference-to-video' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "vidu-video-q2", "images": [ "https://example.com/input.jpg" ], "prompt": "保持参考图主体外观并自然移动"}'

23、4. 输出参数

24、5. 响应示例

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "state": "created", "model": "vidu-video-q3-turbo", "prompt": "@girl 和 @boy 在一起吃火锅", "images": ["https://example.com/girl1.jpg", "https://example.com/boy1.jpg"], "duration": 8, "audio": true, "seed": 0, "credits": 100, "created_at": "2026-07-31T15:41:31.968Z", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

25、6. 错误码

请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。

27、1. 接口描述

以两张图片（首帧 + 尾帧）为端点生成过渡视频，可选文本提示词、推荐提示词、音视频直出与 BGM。

接口： POST https://tokenhub.tencentmaas.com/v1/wand/vidu/start-end-to-video

28、2. 输入参数

注意：说明：

注意：建议首帧与尾帧图片保持相近的分辨率与比例，以获得最佳过渡效果。

29、3. 请求示例

curl -X POST 'https://tokenhub.tencentmaas.com/v1/wand/vidu/start-end-to-video' \\ -H 'Authorization: Bearer YOUR_API_KEY' \\ -H 'Content-Type: application/json' \\ -d '{ "model": "vidu-video-q3-turbo", "images": ["https://example.com/start.jpg", "https://example.com/end.jpg"], "prompt": "从首帧自然过渡到尾帧", "duration": 5, "resolution": "720p"}'

30、4. 输出参数

31、5. 响应示例

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "state": "created", "model": "vidu-video-q3-turbo", "prompt": "从首帧自然过渡到尾帧", "images": ["https://example.com/start.jpg", "https://example.com/end.jpg"], "duration": 5, "seed": 0, "resolution": "720p", "credits": 100, "created_at": "2026-07-31T15:41:31.968Z", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"}

32、6. 错误码

请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。

34、1. 接口描述

各生成接口共用的任务查询方式：提交任务返回 task_id 后，通过本接口轮询任务状态，成功后从结果中获取视频地址。

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

注意：说明：

注意：路径中的 {task_id} 即提交任务时返回的 task_id（示例中以 YOUR_TASK_ID 占位）。视频生成约需 1~5 分钟，建议每 5~10 秒轮询一次。

35、2. 输入参数

36、3. 请求示例

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

37、4. 输出参数

38、5. 响应示例

生成成功：

{ "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d", "state": "success", "model": "vidu-video-q3-turbo", "prompt": "一只小猫在月光下奔跑，镜头跟随", "duration": 5, "seed": 0, "resolution": "720p", "creations": [ { "url": "https://aigc-video.cos.myqcloud.com/xxx/result.mp4", "cover_url": "https://aigc-video.cos.myqcloud.com/xxx/cover.jpg" } ], "credits": 100, "created_at": "2026-07-31T15:41:31.968Z", "request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2", "tokenhub_usage": { "total_tokens": 102655 }}

39、6. 错误码

请求级错误码见 附录：统一错误码。

41、统一错误码

42、各接口时长取值速查

注意：duration 取值范围随接口能力变化，不是仅由模型决定。例如同为 q3-turbo，文生视频可传 1~16 秒，但参考生视频最小为 3 秒。

43、素材通用约束

图片：格式 png / jpeg / jpg / webp；像素 ≥ 128×128；比例须小于 1:4 或 4:1；单图 ≤ 50MB；POST body ≤ 20MB；支持 URL 或 Base64（Base64 须带 data:image/png;base64, 前缀）。

视频（仅 q2-pro 参考生支持）：格式 mp4 / avi / mov；像素 ≥ 128×128；比例 < 1:4 或 4:1；参考视频 ≤ 100MB；主体视频 5 秒以内、Base64 解码 < 20MB。

44、主体引用语法

在参考生视频的 subjects 方式中，通过 subjects[].name 定义主体名，在 prompt 中以 @主体名 引用（如 @girl 和 @boy 在一起吃火锅）。主体名避免互为子串。

46、1. 七款视频模型如何选择？

·最新旗舰预览版、需要 2K / 4K 高分辨率或大容量参考（15 张图 + 3 段音频）：vidu-video-q4-preview（仅支持图生、参考生）；

·速度成本优先、要智能切镜/音画同出：vidu-video-q3-turbo；

·多机位一致性更出色：vidu-video-q3；

·高画质：vidu-video-q3-pro；

·参考生需要视频参考/视频主体：vidu-video-q2-pro（唯一支持视频输入）；

·动态效果好、细节丰富：vidu-video-q2；

·Q2 快速版：vidu-video-q2-turbo。

47、2. subjects 主体方式和 images 直接参考方式有什么区别？

·subjects 方式：可定义多个命名主体，在 prompt 中用 @主体名 灵活引用，适合多主体交互场景；prompt 上限 5000 字符；

·images/videos 直接方式：直接传参考素材，不支持命名引用；prompt 上限 2000 字符。

48、3. audio 和 bgm 有什么区别？

audio 是音视频直出（输出带台词/音效的有声视频），q3 系列与 q4-preview 支持（q4-preview 图生默认开启，参考生需显式传 true）；bgm 是添加背景音乐，q3 系列与 q4-preview 不生效，q2 系列 duration 为 9/10 秒时不生效。

49、4. 哪些接口可以指定画面宽高比？

仅文生视频、多图参考生视频支持 aspect_ratio 参数；图生视频、首尾帧生视频无此参数，输出画幅跟随输入图片比例。

50、5. 生成结果视频链接会过期吗？

会过期。生成结果为临时地址，有效期 12 小时，请在任务成功后及时下载 creations[].url 中的视频并转存到自有存储，不要长期依赖该链接。