产品公告
产品简介
- 产品概述
- 模型列表
产品计费
快速入门
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
常见问题
相关协议
词汇表

Vidu 生视频调用指南

下载

聚焦模式

字号

最后更新时间： 2026-11-02 16:04:44

本文档已由 AI 辅助审校

概述
Vidu 是生数科技推出的视频生成模型系列，支持文生视频、图生视频、多图参考生视频、首尾帧生视频等能力，具备智能切镜、音画同出等特性。本文介绍如何通过 TokenHub 调用 Vidu 的四款视频模型：vidu-video-q4-preview、vidu-video-q3、vidu-video-q3-pro、vidu-video-q3-turbo。
前提条件
已 注册腾讯云 账号并开通 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（用量消耗）。
模型列表
模型名称
model 参数值
支持能力
视频时长（秒）
清晰度档位
选型建议
Vidu-Video-q4-preview
vidu-video-q4-preview
图生 / 参考生 / 音画同出
3 ~ 16
540p / 720p / 1080p / 2K / 4K
旗舰预览版，支持 2K/4K 输出，参考图最多 15 张、参考音频最多 3 段
Vidu-Video-q3.0
vidu-video-q3
参考生 / 智能切镜 / 音画同出
参考生 3~16
540p / 720p / 1080p
多机位一致性更出色
Vidu-Video-q3.0-pro
vidu-video-q3-pro
文生 / 图生 / 首尾帧 / 智能切镜 / 音画同出
文生、图生、首尾帧 1~16
540p / 720p / 1080p
Q3 高画质版
Vidu-Video-q3.0-turbo
vidu-video-q3-turbo
文生 / 图生 / 参考生 / 首尾帧 / 智能切镜 / 音画同出
文生、图生、首尾帧 1~16；参考生 3~16
540p / 720p / 1080p
生成速度最快、性价比最高
说明：
各接口实际支持的 model 与 duration 取值以各接口「输入参数」为准，不同能力的时长范围存在差异，请参见 附录：各接口时长取值速查。
q3 系列：支持智能切镜与音画同出（audio），分辨率支持 540p / 720p / 1080p。
q4-preview：目前仅支持图生视频与参考生视频；音画同出（audio）图生视频默认开启，参考生视频需显式传 true；分辨率额外支持 2K / 4K，默认 720p；参考生视频最多支持 15 张参考图 + 3 段参考音频（sounds）。
文生视频
1. 接口描述
通过纯文本提示词创建文生视频任务，可指定时长、比例、分辨率与音视频直出等参数。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/text-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型名称。取值：vidu-video-q3-turbo、vidu-video-q3-pro
prompt
是
string
文本提示词。≤ 5000 字符。
duration
否
integer
视频时长（秒）。可选 1 ~ 16，默认 5。
aspect_ratio
否
string
画面宽高比。默认 16:9；可选 16:9 / 9:16 / 3:4 / 4:3 / 1:1（部分比例仅特定模型支持）。
resolution
否
string
分辨率。可选 540p / 720p / 1080p，默认值依模型与时长而定。
audio
否
boolean
是否音视频直出（输出带台词/音效的有声视频）。默认视模型而定。
audio_type
否
string
音频类型（audio=true 时必填）。默认 all；可选 all / speech_only / sound_effect_only。
seed
否
integer
随机种子。不传或传 0 时使用随机数。
payload
否
string
透传参数。≤ 1,048,576 字符。
watermark
否
boolean
是否添加水印。默认 false。
wm_position
否
integer
水印位置。TokenHub 不支持该参数。开启 watermark 默认添加腾讯水印在左上角。
wm_url
否
string
自定义水印图片 URL；不传使用默认水印。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/text-to-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "vidu-video-q3-turbo",
  "prompt": "一只小猫在月光下奔跑，镜头跟随",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": true
}'
说明：
将示例中的 model 替换为 vidu-video-q3-pro，即可调用对应模型；duration / aspect_ratio / resolution / audio 等参数详见上方输入参数。
4. 输出参数
字段
类型
说明
task_id
string
Vidu 生成的任务 ID
state
string
处理状态：created / queueing / processing / success / failed
model
string
本次调用的模型名称
prompt
string
本次调用的提示词参数
duration
integer
本次调用的视频时长参数
aspect_ratio
string
本次调用的比例参数
resolution
string
本次调用的分辨率参数
audio
boolean
本次调用是否开启音视频直出
seed
integer
本次调用的随机种子参数
credits
integer
本次调用消耗的积分数
created_at
string
任务创建时间（ISO 8601）
request_id
string
唯一请求标识，用于排查问题。
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-intl.tencentcloudmaas.com/v1/wand/vidu/image-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型名称。取值：vidu-video-q4-preview、vidu-video-q3-turbo、vidu-video-q3-pro
images
是
array[string]
图片 images：支持 1 张图片输入，支持 URL 和 Base64 格式。图片格式：png/jpeg/jpg/webp，图片比例需要小于 1:4 或者 4:1；
1. Base64：图片大小 ≤ 15MB，转为 Base64 大小和 ≤ 20MB；格式要求：data:image/<图片格式>;base64,。注：图片为 jpg 时图片格式填 jpeg。
2. URL：单个文件大小 ≤ 50MB；需要公网可访问（http/https）。
prompt
否
string
文本提示词。≤ 5000 字符。使用 is_rec 时本参数被忽略。
audio
否
boolean
是否音视频直出（输出带台词/音效的有声视频）。默认 true。
audio_type
否
string
音频类型（audio=true 时必填）。默认 all；可选 all / speech_only / sound_effect_only。
is_rec
否
boolean
是否使用推荐提示词。true 时系统自动推荐并生成（每任务多消耗 10 积分）。
duration
否
integer
视频时长（秒）。q4-preview：3 ~ 16；q3-turbo / q3-pro：1 ~ 16。默认 5。
resolution
否
string
分辨率。q4-preview：540p / 720p / 1080p / 2K / 4K，默认 720p；q3-turbo / q3-pro：540p / 720p / 1080p，默认值依模型与时长而定。
seed
否
integer
随机种子。不传或传 0 时使用随机数。
payload
否
string
透传参数。≤ 1,048,576 字符。
watermark
否
boolean
是否添加水印。默认 false。
wm_position
否
integer
水印位置。TokenHub 不支持该参数。开启 watermark 默认添加腾讯水印在左上角。
wm_url
否
string
自定义水印图片 URL；不传使用默认水印。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/image-to-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "vidu-video-q4-preview",
  "images": ["https://example.com/start.jpg"],
  "prompt": "让画面中的主体自然运动，镜头缓慢推近",
  "duration": 5,
  "resolution": "720p",
  "audio": true
}'
说明：
将示例中的 model 替换为 vidu-video-q3-turbo 或 vidu-video-q3-pro，即可调用对应模型；duration / resolution / audio 等参数详见上方输入参数。
4. 输出参数
字段
类型
说明
task_id
string
Vidu 生成的任务 ID
state
string
处理状态：created / queueing / processing / success / failed
model
string
本次调用的模型名称
prompt
string
本次调用的提示词参数
images
array[string]
本次调用的图像参数
duration
integer
本次调用的视频时长参数
audio
boolean
本次调用是否音画同出
seed
integer
本次调用的随机种子参数
resolution
string
本次调用的分辨率参数
credits
integer
本次调用消耗的积分数
created_at
string
任务创建时间（ISO 8601）
request_id
string
唯一请求标识，用于排查问题
5. 响应示例
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "state": "created",
  "model": "vidu-video-q4-preview",
  "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. 错误码
请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。
多图参考生视频
1. 接口描述
以参考图片保持主体一致性生成视频，支持两种调用方式：
方式一使用 subjects 主体（可在 prompt 中以 @主体名 引用）；
方式二直接使用顶层 images 参考。两者必选其一。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/reference-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型名称。取值：vidu-video-q4-preview、vidu-video-q3-turbo、vidu-video-q3
subjects
条件必选
array[object]
主体集合（方式一，与 images 二选一）。子字段见下表
images
条件必选
array[string]
参考图片（方式二，与 subjects 二选一）：q4-preview 最多 15 张，支持 URL 和 Base64 格式。图片格式：png/jpeg/jpg/webp，图片比例需要小于 1:4 或者 4:1；
1. Base64：所有图片大小和 ≤ 15MB，转为 Base64 大小和 ≤ 20MB；格式要求：data:image/<图片格式>;base64,。注：图片为 jpg 时图片格式填 jpeg。 
2. URL：单个文件大小 ≤ 50MB；需要公网可访问（http/https）。
prompt
是
string
文本提示词。主体方式 ≤ 5000 字符（可用 @主体名 引用）；直接参考方式 ≤ 2000 字符
auto_subjects
否
boolean
是否使用智能主体库能力。默认 false
audio
否
boolean
是否音视频直出。q3 / q3-turbo 默认 true；q4-preview 不传时按 false 下发，如需音画同出请显式传 true；非主体调用时仅 q3 支持，q4-preview 需使用 subjects 主体方式
audio_type
否
string
音频类型（audio=true 时必填）。默认 all；可选 all / speech_only / sound_effect_only
duration
否
integer
视频时长（秒）。可选 3 ~ 16，默认 5
aspect_ratio
否
string
画面宽高比。默认 16:9；可选 16:9 / 9:16 / 3:4 / 4:3 / 1:1
resolution
否
string
分辨率。q4-preview：540p / 720p / 1080p / 2K / 4K，默认 720p；q3 / q3-turbo：540p / 720p / 1080p，默认值依模型而定
seed / payload / watermark / wm_position / wm_url
否
-
通用配置，同「图生视频」。
subjects 数组元素子字段：
参数名
必选
类型
描述
name
是
string
主体 ID/名称，后续在 prompt 中以 @name 引用。
images
是
array[string]
图片 subjects.images[]：支持 1 ~ 3 张图片输入，支持 URL 和 Base64 格式。图片格式：png/jpeg/jpg/webp，图片比例需要小于 1:4 或者 4:1；
1. Base64：所有图片大小和 ≤ 15MB，转为 Base64 大小和 ≤ 20MB；格式要求：data:image/<图片格式>;base64,。注：图片为 jpg 时图片格式填 jpeg。 
2. URL：单个文件大小 ≤ 50MB；需要公网可访问（http/https）。
说明：
主体数量限制：
q4-preview：最多 15 张参考图 + 3 段参考音频（sounds）。
q3 / q3-turbo：图片/文字主体最多 7 个，不支持视频主体。
3. 请求示例
方式一：subjects 主体
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/reference-to-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "vidu-video-q4-preview",
  "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-intl.tencentcloudmaas.com/v1/wand/vidu/reference-to-video' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "vidu-video-q4-preview",
  "images": [
    "https://example.com/input.jpg"
  ],
  "prompt": "保持参考图主体外观并自然移动"
}'
说明：
将示例中的 model 替换为 vidu-video-q3-turbo 或 vidu-video-q3，即可调用对应模型。
4. 输出参数
字段
类型
说明
task_id
string
Vidu 生成的任务 ID
state
string
处理状态：created / queueing / processing / success / failed
model
string
本次调用的模型名称
prompt
string
本次调用的提示词参数
images
array[string]
本次调用的图像参数
duration
integer
本次调用的视频时长参数
audio
boolean
本次调用是否开启音视频直出
seed
integer
本次调用的随机种子参数
credits
integer
本次调用消耗的积分数
created_at
string
任务创建时间（ISO 8601）
request_id
string
唯一请求标识，用于排查问题
5. 响应示例
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "state": "created",
  "model": "vidu-video-q4-preview",
  "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"
}
6. 错误码
请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。
首尾帧生视频
1. 接口描述
以两张图片（首帧 + 尾帧）为端点生成过渡视频，可选文本提示词、推荐提示词与音视频直出。
接口： POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/start-end-to-video
2. 输入参数
参数名
必选
类型
描述
model
是
string
模型名称。取值：vidu-video-q3-turbo、vidu-video-q3-pro
images
是
array[string]
图片 images：支持 2 张图片输入，支持 URL 和 Base64 格式。首尾帧两张输入图的分辨率需相近，首帧图分辨率 / 尾帧图分辨率须在 0.8 ~ 1.25 之间；图片比例需要小于 1:4 或者 4:1。图片格式：png/jpeg/jpg/webp；Base64：图片大小 ≤ 15MB，转为 Base64 大小和 ≤ 20MB；格式要求：data:image/<图片格式>;base64,。注：图片为 jpg 时图片格式填 jpeg。URL：单个文件大小 ≤ 50MB；需要公网可访问（http/https）。
prompt
否
string
文本提示词。≤ 5000 字符。使用 is_rec 时本参数被忽略。
is_rec
否
boolean
是否使用推荐提示词。true 时系统自动推荐并生成（每任务多消耗 10 积分）。
duration
否
integer
视频时长（秒）。可选 1 ~ 16，默认 5。
resolution
否
string
分辨率。可选 540p / 720p / 1080p，默认值依模型而定。
audio
否
boolean
是否音视频直出。默认 true。
seed / payload / watermark / wm_position / wm_url
否
-
通用配置，同「文生视频」
说明：
建议首帧与尾帧图片保持相近的分辨率与比例，以获得最佳过渡效果。
3. 请求示例
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.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"
}'
4. 输出参数
字段
类型
说明
task_id
string
Vidu 生成的任务 ID
state
string
处理状态：created / queueing / processing / success / failed
model
string
本次调用的模型名称
prompt
string
本次调用的提示词参数
images
array[string]
本次调用的图像参数（首帧、尾帧）
duration
integer
本次调用的视频时长参数
seed
integer
本次调用的随机种子参数
resolution
string
本次调用的分辨率参数
credits
integer
本次调用消耗的积分数
created_at
string
任务创建时间（ISO 8601）
request_id
string
唯一请求标识，用于排查问题
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"
}
6. 错误码
请求失败时返回错误码，具体见错误信息。常见错误码见 附录：统一错误码。
查询任务结果
1. 接口描述
各生成接口共用的任务查询方式：提交任务返回 task_id 后，通过本接口轮询任务状态，成功后从结果中获取视频地址。
接口： GET https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/tasks/{task_id}
说明：
路径中的 {task_id} 即提交任务时返回的 task_id（示例中以 YOUR_TASK_ID 占位）。视频生成约需 1~5 分钟，建议每 5~10 秒轮询一次。
2. 输入参数
参数名
必选
类型
描述
task_id
是
string
任务 ID（路径参数），即提交任务时返回的 task_id
3. 请求示例
curl -X GET 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/vidu/tasks/YOUR_TASK_ID' \\
  -H 'Authorization: Bearer YOUR_API_KEY'
4. 输出参数
字段
类型
说明
task_id
string
任务 ID
state
string
处理状态：created / queueing / processing / success / failed
model
string
本次调用的模型名称
prompt
string
本次调用的提示词参数
duration
integer
本次调用的视频时长参数
seed
integer
本次调用的随机种子参数
resolution
string
本次调用的分辨率参数
creations
array[object]
生成结果列表（成功时返回）
creations[].url
string
生成视频的下载地址，为临时地址，有效期 12 小时，请及时下载转存
creations[].cover_url
string
生成视频的封面图地址
credits
integer
本次调用消耗的积分数
created_at
string
任务创建时间（ISO 8601）
request_id
string
唯一请求标识，用于排查问题
tokenhub_usage
object
用量消耗
tokenhub_usage.total_tokens
integer
本次任务消耗的 token 数，用于计费/对账
5. 响应示例
生成成功：
{
  "task_id": "4-WandVideo-a786becfdc80433b8cff4aa344c8fd3d",
  "state": "success",
  "model": "vidu-video-q4-preview",
  "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 }
}
6. 错误码
state
含义
处理建议
success
生成成功
从 creations[].url 获取结果视频。
processing / queueing
处理中 / 排队中
每 5~10 秒轮询一次，直至 success。
failed
生成失败
查看失败原因，修改后重试；持续失败请联系技术支持并附 request_id。
附录
统一错误码
错误码
错误信息
说明
BadRequest
bad request
不合法的请求
FieldLacking
field is missing or empty
缺少必填字段
FieldUnwanted
unwanted field
传入了不需要的字段
FieldInvalid
invalid field
传入参数未通过合法性校验
FieldItemCountOutOfRange
field item count out of range
字段项数超限（如图片数量超限）
PageSizeOutOfRange
page size out of range
图像尺寸/参数超限
ImageFormatInvalid / VideoFormatInvalid
invalid image/video format
图像/视频格式不符合要求
ImageSizeInvalid
image size invalid
图片尺寸过大或过小
ImageDownloadFailure / VideoDownloadFailure
image/video download failure
下载图片/视频 URL 失败
ImageCheckFaceFailed
Image Check Face Failed
输入图人脸检测失败
ImageCheckBodyJointsFailed
Image Check Body Joints Failed
输入图人体检测失败
NoFaceDetected / MultiFaceDetected
no / multi face detected
未检测到人脸 / 多张人脸
TaskPromptPolicyViolation
prompt policy violation
Prompt 触发安审风控
CreationPolicyViolation
creation policy violation
生成物触发风控
AuditSubmitIllegal / AuditFailed
submit is illegal / audit failed
输入未通过安全审核 / 审核失败
CreditInsufficient
insufficient credits
积分不足
ModelUnavailable
model unavailable
模型不可用
Unauthorized
unauthorized
未鉴权（检查 Authorization）
Forbidden
forbidden
请求没有权限
TaskNotFound / CreationNotFound / NotFound
not found
任务/生成物/资源不存在
QuotaExceeded
quota exceeded
超过并发限制
TooManyRequests
too many requests
请求太频繁
SystemThrottling
system is throttling
资源超过限制（限流）
UserCancelled / Canceled
user cancelled / request canceled
用户手动终止 / 请求被取消
InternalServiceFailure
internal service failure
服务器内部错误
Unknown
unknown
未知原因
各接口时长取值速查
接口
vidu-video-q4-preview
q3 系列（q3 / q3-pro / q3-turbo）
文生视频
不支持
1 ~ 16，默认 5
图生视频
3 ~ 16，默认 5
1 ~ 16，默认 5
多图参考生视频
3 ~ 16，默认 5
3 ~ 16，默认 5
首尾帧生视频
不支持
1 ~ 16，默认 5
注意：
duration 取值范围随接口能力变化，不是仅由模型决定。例如同为 q3-turbo，文生视频可传 1~16 秒，但参考生视频最小为 3 秒。
素材通用约束
图片：格式 png / jpeg / jpg / webp；像素 ≥ 128×128；比例须小于 1:4 或 4:1；单图 ≤ 50MB；POST body ≤ 20MB；支持 URL 或 Base64（Base64 须带 data:image/png;base64, 前缀）。
主体引用语法
在参考生视频的 subjects 方式中，通过 subjects[].name 定义主体名，在 prompt 中以 @主体名 引用（如 @girl 和 @boy 在一起吃火锅）。主体名避免互为子串。
常见问题
1. 四款视频模型如何选择？
旗舰预览版、需要 2K / 4K 高分辨率或大容量参考（15 张图 + 3 段音频）：vidu-video-q4-preview（仅支持图生、参考生）；
速度成本优先、要智能切镜/音画同出：vidu-video-q3-turbo；
多机位一致性更出色：vidu-video-q3；
高画质：vidu-video-q3-pro。
2. subjects 主体方式和 images 直接参考方式有什么区别？
subjects 方式：可定义多个命名主体，在 prompt 中用 @主体名 灵活引用，适合多主体交互场景；prompt 上限 5000 字符；支持音画同出（audio）。
images 直接方式：直接传参考素材，不支持命名引用；prompt 上限 2000 字符。
3. 如何开启音画同出？
audio 为音视频直出（输出带台词/音效的有声视频），q3 系列与 q4-preview 均支持：
q3 系列：图生、参考生、首尾帧默认开启，文生视频默认值视模型而定；
q4-preview：图生视频默认开启；参考生视频需使用 subjects 主体方式并显式传 audio: true。
两者均不支持 bgm 背景音乐参数。
4. 哪些接口可以指定画面宽高比？
仅文生视频、多图参考生视频支持 aspect_ratio 参数；图生视频、首尾帧生视频无此参数，输出画幅跟随输入图片比例。
5. 生成结果视频链接会过期吗？
会过期。生成结果为临时地址，有效期 12 小时，请在任务成功后及时下载 creations[].url 中的视频并转存到自有存储，不要长期依赖该链接。
﻿
﻿

帮助和支持

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

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

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

文档反馈

模型名称	model 参数值	支持能力	视频时长（秒）	清晰度档位	选型建议
Vidu-Video-q4-preview	`vidu-video-q4-preview`	图生 / 参考生 / 音画同出	3 ~ 16	540p / 720p / 1080p / 2K / 4K	旗舰预览版，支持 2K/4K 输出，参考图最多 15 张、参考音频最多 3 段
Vidu-Video-q3.0	`vidu-video-q3`	参考生 / 智能切镜 / 音画同出	参考生 3~16	540p / 720p / 1080p	多机位一致性更出色
Vidu-Video-q3.0-pro	`vidu-video-q3-pro`	文生 / 图生 / 首尾帧 / 智能切镜 / 音画同出	文生、图生、首尾帧 1~16	540p / 720p / 1080p	Q3 高画质版
Vidu-Video-q3.0-turbo	`vidu-video-q3-turbo`	文生 / 图生 / 参考生 / 首尾帧 / 智能切镜 / 音画同出	文生、图生、首尾帧 1~16；参考生 3~16	540p / 720p / 1080p	生成速度最快、性价比最高

参数名	必选	类型	描述
model	是	string	模型名称。取值：`vidu-video-q3-turbo`、`vidu-video-q3-pro`
prompt	是	string	文本提示词。≤ 5000 字符。
duration	否	integer	视频时长（秒）。可选 1 ~ 16，默认 5。
aspect_ratio	否	string	画面宽高比。默认 16:9；可选 16:9 / 9:16 / 3:4 / 4:3 / 1:1（部分比例仅特定模型支持）。
resolution	否	string	分辨率。可选 540p / 720p / 1080p，默认值依模型与时长而定。
audio	否	boolean	是否音视频直出（输出带台词/音效的有声视频）。默认视模型而定。
audio_type	否	string	音频类型（audio=true 时必填）。默认 all；可选 all / speech_only / sound_effect_only。
seed	否	integer	随机种子。不传或传 0 时使用随机数。
payload	否	string	透传参数。≤ 1,048,576 字符。
watermark	否	boolean	是否添加水印。默认 false。
wm_position	否	integer	水印位置。TokenHub 不支持该参数。开启 watermark 默认添加腾讯水印在左上角。
wm_url	否	string	自定义水印图片 URL；不传使用默认水印。

字段	类型	说明
task_id	string	Vidu 生成的任务 ID
state	string	处理状态：created / queueing / processing / success / failed
model	string	本次调用的模型名称
prompt	string	本次调用的提示词参数
duration	integer	本次调用的视频时长参数
aspect_ratio	string	本次调用的比例参数
resolution	string	本次调用的分辨率参数
audio	boolean	本次调用是否开启音视频直出
seed	integer	本次调用的随机种子参数
credits	integer	本次调用消耗的积分数
created_at	string	任务创建时间（ISO 8601）
request_id	string	唯一请求标识，用于排查问题。

state	含义	处理建议
success	生成成功	从 `creations[].url` 获取结果视频。
processing / queueing	处理中 / 排队中	每 5~10 秒轮询一次，直至 success。
failed	生成失败	查看失败原因，修改后重试；持续失败请联系技术支持并附 request_id。

错误码	错误信息	说明
BadRequest	bad request	不合法的请求
FieldLacking	field is missing or empty	缺少必填字段
FieldUnwanted	unwanted field	传入了不需要的字段
FieldInvalid	invalid field	传入参数未通过合法性校验
FieldItemCountOutOfRange	field item count out of range	字段项数超限（如图片数量超限）
PageSizeOutOfRange	page size out of range	图像尺寸/参数超限
ImageFormatInvalid / VideoFormatInvalid	invalid image/video format	图像/视频格式不符合要求
ImageSizeInvalid	image size invalid	图片尺寸过大或过小
ImageDownloadFailure / VideoDownloadFailure	image/video download failure	下载图片/视频 URL 失败
ImageCheckFaceFailed	Image Check Face Failed	输入图人脸检测失败
ImageCheckBodyJointsFailed	Image Check Body Joints Failed	输入图人体检测失败
NoFaceDetected / MultiFaceDetected	no / multi face detected	未检测到人脸 / 多张人脸
TaskPromptPolicyViolation	prompt policy violation	Prompt 触发安审风控
CreationPolicyViolation	creation policy violation	生成物触发风控
AuditSubmitIllegal / AuditFailed	submit is illegal / audit failed	输入未通过安全审核 / 审核失败
CreditInsufficient	insufficient credits	积分不足
ModelUnavailable	model unavailable	模型不可用
Unauthorized	unauthorized	未鉴权（检查 Authorization）
Forbidden	forbidden	请求没有权限
TaskNotFound / CreationNotFound / NotFound	not found	任务/生成物/资源不存在
QuotaExceeded	quota exceeded	超过并发限制
TooManyRequests	too many requests	请求太频繁
SystemThrottling	system is throttling	资源超过限制（限流）
UserCancelled / Canceled	user cancelled / request canceled	用户手动终止 / 请求被取消
InternalServiceFailure	internal service failure	服务器内部错误
Unknown	unknown	未知原因

接口	vidu-video-q4-preview	q3 系列（q3 / q3-pro / q3-turbo）
文生视频	不支持	1 ~ 16，默认 5
图生视频	3 ~ 16，默认 5	1 ~ 16，默认 5
多图参考生视频	3 ~ 16，默认 5	3 ~ 16，默认 5
首尾帧生视频	不支持	1 ~ 16，默认 5

tencent cloud

大模型服务平台 TokenHub

Vidu 生视频调用指南

概述

前提条件

调用流程

模型列表

文生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

图生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

多图参考生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

首尾帧生视频

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

查询任务结果

1. 接口描述

2. 输入参数

3. 请求示例

4. 输出参数

5. 响应示例

6. 错误码

附录

统一错误码

各接口时长取值速查

素材通用约束

主体引用语法

常见问题

1. 四款视频模型如何选择？

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

3. 如何开启音画同出？

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

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

帮助和支持