认证
authorization string 必填
所有 API 均使用 Bearer Token 鉴权
获取 API Key：
访问 API Key 管理页面 获取 API Key
用法：
将以下 Header 添加到请求中：
Authorization: Bearer YOUR_API_KEY参数
model 放在请求体顶层, 以下生成参数放在 input[0].params 中
model string 必填
请求使用的模型 ID
值：viduq4_preview_reference2video
images array<string> 必填
参考图片, 根据图片中的主体生成保持主体一致性的视频
支持 1 至 15 张图片
支持可访问的图片 URL 或带 MIME 前缀的 Base64 data URI
支持格式：png、jpeg、jpg、webp
HTTP POST 请求体不超过 20MB
Base64 示例：data:image/png;base64,{base64_encode}
prompt string 必填
生成视频的文本描述
长度不超过 20000 个字符
可通过 [@subjects_name] 引用主体内容
sounds array<string>
参考音频, 用于引导视频中的声音
最多支持 3 个音频, 每个音频时长为 3 至 12 秒
支持 mp3 格式, 单个音频大小不超过 50MB
支持可访问的音频 URL 或带内容类型前缀的 Base64 编码
HTTP POST 请求体不超过 20MB
audio boolean
是否生成带声音的视频
true：输出带声音的视频, 包括台词和音效
false：输出静音视频
默认值：true
可选值：true、false
duration integer
视频时长, 单位为秒
默认值：5
范围：3 - 16
aspect_ratio string
输出视频的画面比例
默认值：16:9
可选值：1:1、9:16、16:9、3:4、4:3
resolution string
输出视频的分辨率
默认值：720p
可选值：540p、720p、1080p、2K、4K
seed integer
随机种子, 省略或传 0 时使用随机数, 手动设置时使用传入的值
默认值：0
payload string
自定义数据, 原样传递
长度不超过 1048576 个字符
callback_url string
任务状态变化时接收通知的回调地址, 需在创建任务时设置
Vidu 向该地址发送 POST 请求, 回调采用 Vidu 原生任务结构和状态：processing、success、failed
成功或失败状态的回调发送失败时重试 3 次, Vidu 使用回调签名进行验证
平台最终任务状态和视频结果通过下方查询接口获取
轮询
由于结果生成需要时间，您需要在创建任务后轮询任务状态
初始响应只返回任务 ID 和初始状态等信息，最终生成结果需通过使用该任务 ID 轮询任务状态接口获取
轮询请求与响应示例见右侧
使用创建响应中的 id 替换查询 URL 中的 {task_id}
创建响应的 status 为 completed 时, 仍需查询任务获取视频结果
查询状态为 in_progress 时继续轮询, 为 completed 且包含 output 时读取 output[].content[].url, 为 failed 时读取 error
失败响应示例
{
"id": "task_id",
"created_at": 1791763200000,
"status": "failed",
"model": "viduq4_preview_reference2video",
"error": {
"message": "Video generation failed"
},
"output": []
}计费
按输出分辨率档位和生成时长计费, 价格以平台模型价格配置为准
最终费用见成功查询响应中的 usage.cost, 单位为美元
响应格式
error object
错误信息, 仅在状态为 failed 时存在
code
string错误码
message
string详细错误信息
output array
生成结果, 仅在状态为 completed 时存在
content
array生成的资源内容列表
type
string资源类型
值:
image｜videourl
string处理后的资源 URL
jobId
string远端任务 ID
usage object
使用统计, 仅在状态为 completed 时存在
cost
string总费用（美元）
discount
number折扣金额
metadata object
元数据信息