Skip to main content
POST
Vidu Q3 视频生成
  • 异步任务接口,提交后返回统一 generation.task
  • 当前对外模型:viduq3-pro-fastviduq3-adviduq3-dramaviduq3-mix
viduq3-adviduq3-dramaviduq3-mix 不是纯文生视频模型。不要只传 prompt;至少需要参考素材。否则上游通常会返回 InvalidParameter,例如 Missing required field 'subjects' in request body

认证

string
必填
所有接口均需要使用 Bearer Token 认证。

支持模型

请求参数

string
必填
只支持以下 4 个对外模型名:
  • viduq3-pro-fast
  • viduq3-ad
  • viduq3-drama
  • viduq3-mix
string
必填
提示词。即使是参考生成模型也建议始终填写 prompt,用于描述镜头、动作、节奏和风格。
string[]
参考图片 URL 列表。
  • viduq3-pro-fast:只使用第 1 张图片,作为首帧
  • viduq3-ad / viduq3-drama / viduq3-mix:建议传 1 张或多张主体/风格参考图
兼容字段:
  • input_reference
  • reference_images
  • images
  • image
string
参考视频 URL。viduq3-ad / viduq3-drama / viduq3-mix 推荐传入。等价于传入一个主参考视频。
array
参考视频列表。viduq3-ad / viduq3-drama / viduq3-mix 使用。每一项支持:
  • video_url
  • refer_type(可选)
  • keep_original_sound(可选)
integer
默认值:5
视频时长,单位秒。默认 5
string
默认值:"720P"
分辨率,支持 720P1080P建议:
  • viduq3-drama 优先使用 1080P
boolean
是否生成音频。当前服务端默认行为:
  • viduq3-pro-fast:默认 true
  • viduq3-ad:默认 true
  • viduq3-mix:默认 true
  • viduq3-drama:建议显式传值,不要依赖默认值
boolean
默认值:false
是否添加水印。
integer
随机种子。
object
扩展参数,会按阿里视频请求结构尝试透传。常见用法:
  • metadata.input.first_frame_url
  • metadata.input.last_frame_url
  • metadata.input.audio_url
  • metadata.parameters.audio
  • metadata.parameters.watermark
viduq3-ad / viduq3-drama / viduq3-mix 在上游侧可能要求主体结构化输入(如 subjects)。如果只传纯文本 prompt,通常会直接失败。

输入规则

1. viduq3-pro-fast

  • 这是首帧图生视频模型
  • 至少传 1 张图
  • 多张图时当前只会取第 1 张
  • 适合“让静态图片动起来”的场景

2. viduq3-ad / viduq3-drama / viduq3-mix

  • 这是参考视频生成模型,不建议纯 prompt 调用
  • 推荐至少传:
    • 1 个参考视频:urlvideo_list
    • 1 张参考图:image_urls 或兼容图片字段
  • 如果缺少主体/参考素材,上游可能返回:
    • InvalidParameter
    • Missing required field 'subjects' in request body

请求示例

viduq3-pro-fast 首帧图生视频

viduq3-ad 参考视频生成

viduq3-drama 剧情型参考生成

viduq3-mix 混合参考生成

提交成功响应

查询任务

GET /v1/videos/generations/{task_id} 处理中:
成功:
失败:

说明

  • 提交后由 ToAPIs 统一轮询上游任务状态,再返回标准视频任务结果。
  • viduq3-pro-fast 是当前最稳定的接入形态,适合首帧图生视频。
  • viduq3-adviduq3-dramaviduq3-mix 对参考素材要求更严格,接入前建议先按上面的示例准备完整素材,不要只传 prompt。