认证
authorization string 必需
所有 API 都需要通过 Bearer Token 进行身份验证.
获取 API Key:
访问 API Key 管理页面 获取您的 API Key
使用方式:
添加到请求头:
Authorization: Bearer YOUR_API_KEY参数
model string 必填
请求使用的模型 ID
值: viduq2_pro_fast_reference2video
subjects array 必填
图片主体信息, 支持 1 - 7 个主体, 主体图片共 1 - 7 张
id
string必填主体 ID, 后续生成时可以通过
@主体id的方式使用
images
array必填该主体对应的图片 URL, 每个主体最多支持
3张图片格式要求：
支持传入图片 Base64 编码或图片 URL（确保可访问）
支持格式：png, jpeg, jpg, webp
图片像素不能小于128×128, 且比例需要小于1:4或者4:1, 且大小不超过50MB
请注意, http 请求的 post body 不超过20MB, 且编码必须包含适当的内容类型字符串. 例如：data:image/png;base64,{base64_encode}
voice_id
string音色 ID, 用来决定视频中的声音音色，为空时系统会自动推荐, 可选枚举值参考列表：新音色列表
prompt string 必填
生成视频的文本描述，字符长度不能超过 2000 个字符
使用 subjects 主体参数时, 可以通过 @主体id 来表示主体内容, 例如：“@1 和 @2 在一起吃火锅, 并且旁白音说火锅大家都爱吃.”
audio boolean
是否使用音视频直出能力
当为 true 时, 使用音视频直出能力；当为 false 时, 不使用音视频直出能力
可选值: true, false
默认值: false
duration integer
视频时长, 单位为秒
可选值: 1, 2, 3, 4, 5, 6, 7, 8
默认值: 5
seed integer
随机种子，当默认不传或者传 0 时, 使用随机数替代，手动设置则使用设置的种子
aspect_ratio string
比例
注意: q2 模型支持任意宽高比
可选值: 16:9, 9:16, 1:1
默认值: 16:9
resolution string
分辨率参数
可选值: 720p, 1080p
默认值: 720p
payload string
透传参数，不做任何处理, 仅数据传输，最多 1048576 个字符
off_peak boolean
注意: 暂不可用
错峰模式，错峰模式消耗的积分更低. 错峰模式下提交的任务会在 48 小时内生成. 未能完成的任务会被自动取消, 并返还该任务的积分
当为 true 时错峰生成视频；当为 false 时即时生成视频
注意: 音视频直出功能不支持错峰模式
可选值: true, false
默认值: false
watermark boolean
是否添加水印. 当为 true 时添加水印；当为 false 时不添加水印
目前水印内容为固定, 内容由 AI 生成, 默认不加
可选值: true, false
默认值: false
wm_position integer
水印位置, 表示水印出现在图片的位置
可选值: 1（左上角）, 2（右上角）, 3（右下角）, 4（左下角）
默认值: 3
wm_url string
水印内容, 此处为图片 URL，不传时, 使用默认水印：内容由 AI 生成
meta_data string
元数据标识, JSON 格式字符串, 透传字段
您可以自定义格式或使用示例格式. 示例如下：
{
"Label": "your_label",
"ContentProducer": "yourcontentproducer",
"ContentPropagator": "your_content_propagator",
"ProduceID": "yourproductid",
"PropagateID": "your_propagate_id",
"ReservedCode1": "yourreservedcode1",
"ReservedCode2": "your_reserved_code2"
}该参数为空时, 默认使用 vidu 生成的元数据标识
callback_url string
回调 URL
轮询
由于视频生成需要时间, 您需要在创建任务后轮询任务状态
初始响应返回任务 ID 和初始状态. 实际的生成结果必须通过轮询任务状态端点来获取
响应格式
error object
错误信息. 仅在 status 为 failed 时出现
code
string错误代码
message
string详细错误消息
output array
生成结果. 仅在 status 为 completed 时出现
task_id
string任务 ID
task_status
string任务状态
可选值:
processing,done,failed
results
array生成的视频列表
type
string资源类型
值:
videourl
string视频 CDN 地址
usage object
使用统计信息. 仅在 status 为 completed 时出现
cost
string总费用（美元）
discount
number折扣金额
metadata object
元数据信息
remote_task_id
string远程任务 ID
model
string使用的模型名称
错误码
| 错误码 | 描述 |
|---|---|
| 008017001 | 当 audio=true 时, subjects 参数必填 |
| 008017002 | images 或 subjects 参数必须提供其中之一 |
| 008017003 | images 参数必须包含 1-7 张图片 |
| 008017095 | 内部生成错误 |
| 008017096 | 结果解析异常 |
| 008017097 | HTTP 错误响应 |
| 008017098 | 状态检查异常 |
| 008017099 | 任务创建异常 |