POST/ent/v2/reference2video

Vidu 参考生视频（主体调用）

将参考图片组织为具名主体，在提示词中用 @主体名称描述动作，适合分别控制人物或物体。

API Key application/json

功能与模型

官方主体参考型号为 viduq3-turbo、viduq3、viduq2、viduq1 和 vidu2.0。官方说明 viduq3-mix 暂不支持 entities/subjects；下表只列当前插件离线核验的主体组合。

当前插件已核验组合	模型	秒数	分辨率
主体参考	`viduq2`	1–10（整数）	540p / 720p / 1080p
主体参考	`viduq1`	5	1080p

官方型号（2026-10-02）：viduq3-turbo、viduq3、viduq2、viduq1、vidu2.0。这是 Vidu 官方动作页面的型号清单；青云TOP 当前 pricing 快照未匹配到 Vidu，且本地插件离线核验范围仍为旧型号。提交前请用当前 API Key 调用 GET /v1/models，只有返回该型号且分组开放时才可使用；不能只替换 model 字符串。

主体参考请先确认当前 Key 是否开放对应型号。当前可执行示例使用 viduq2；vidu2.0 不能仅通过 metadata.subjects 提交图片来绕过 Responses/视频入口的输入校验。

1. 设置鉴权

所有本站请求使用基础地址 https://top.qingyuntop.ai。请求头为 Authorization: Bearer YOUR_API_KEY，将 YOUR_API_KEY 替换为青云TOP API 的 API Key，保留 Bearer 后的一个空格。无需额外登录接口，也不需要 Vidu 厂商 Token。

2. 调用模型生成

POST https://top.qingyuntop.ai/v1/videos，Content-Type: application/json。同时设置 metadata.action: "reference_to_video" 和 metadata.subjects 数组。只有 subjects 而不写 action 时，接口仍可能按顶层素材自动判断为文生。

参数	类型	说明
`model`	string	必填。当前插件离线核验为 viduq2、viduq1；官方主体参考页面还列出 viduq3-turbo、viduq3。官方说明 viduq3-mix 暂不支持 entities/subjects；vidu2.0 也不能仅靠 metadata.subjects 绕过输入校验。新增型号需先由 GET /v1/models 确认开放。
`metadata.auto_subjects`	boolean	选填，放入 metadata，默认 false。上游智能主体库能力；本示例使用显式 subjects，不依赖已创建主体库。
`metadata.subjects`	object[]	必填，放入 metadata。使用图片主体；官方规定图片或文本主体总数不超过 7。不要与顶层 images 混用来规避校验。
`metadata.subjects[].name`	string	必填，主体名称，例如 astronaut；在 prompt 中用 @astronaut 引用。
`metadata.subjects[].images`	string[]	必填，每个主体最多 3 张图片 URL 或 data URL。
`metadata.subjects[].voice_id`	string	选填，主体音色 ID。只有对应音视频能力可用时才设置；本目录不提供音色管理入口。
`prompt`	string	必填，最多 5000 字符。通过 @主体名称指定各主体的行为。
`metadata.audio`	boolean	选填，放入 metadata。此官方主体参考接口允许请求音视频输出，默认 false；依上游能力生效，不代表文生/首尾帧支持此字段。
`metadata.audio_type`	string	音视频细分参数，放入 metadata；官方说明默认 all，并区分音效加人声、仅人声、仅音效。正文枚举存在大小写和连字符混用，确认上游取值后再启用。基础示例只生成视频。
`seconds`	integer	选填；本站优先使用 seconds（单位：秒），不要同时设置 duration。模型组合见本页表格。
`metadata.seed`	integer	选填，放入 metadata。整数随机种子；省略时由上游随机生成，不保证跨任务像素级一致。
`metadata.aspect_ratio`	string	选填，放入 metadata，默认 16:9。示例使用 16:9；viduq1 可选 16:9、9:16、1:1。官方主体 Q2 页称支持任意比例，常规接入优先使用 16:9、9:16、1:1、3:4、4:3。
`resolution`	string	选填。显式使用本页允许的档位；不表示画面比例。
`metadata.movement_amplitude`	string	选填，放入 metadata。auto（默认）、small、medium、large；viduq2 不生效。
`metadata.payload`	string	选填，放入 metadata。业务透传字符串，最多 1048576 字符；统一视频结果不会承诺回显，关联任务请自行保存返回 ID。
`metadata.off_peak`	boolean	选填，放入 metadata，默认 false。初次接入建议保持 false；当前文档不提供取消任务入口，不承诺官方直连的退款规则适用于本站。
`metadata.callback_url`	string	选填，上游回调地址，放入 metadata。不能用本站 API Key 验证厂商回调签名；建议先采用查询接口。详见状态码、错误与回调。

图片或文本主体总数通常不超过 7，每个主体最多 3 张参考图片。每张图片至少 128×128，宽高比建议位于 1:4 到 4:1 之间；支持 PNG、JPEG/JPG、WebP。URL 图片不超过 50MB，整个 JSON 请求体不超过 20MB；Base64 使用带 MIME 前缀的 data URL。

本页使用图片主体；视频主体、主体库创建与声音克隆不属于本站入口。主体名称必须与 prompt 中的 @名称 一致。

代码示例

点击标签切换 cURL、Python 或 Node.js。cURL 为 Bash 写法；Python 需安装 requests；Node.js 使用 18 或更新版本（含导入语句时保存为 .mjs）。图片示例使用 Vidu 官方示例素材，也可换成你自己的公开可访问图片 URL。

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "viduq2",
  "prompt": "@astronaut 在月球表面缓缓行走，保持服装和人物外观一致。",
  "seconds": 5,
  "resolution": "720p",
  "metadata": {
    "action": "reference_to_video",
    "subjects": [
      {
        "name": "astronaut",
        "images": [
          "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png"
        ]
      }
    ],
    "aspect_ratio": "16:9"
  }
}'

查询与下载

创建成功后保存返回的 id，按查询任务与下载视频查询。只有 status=completed 才下载；创建请求返回成功不等于视频已经生成。

若改用 Responses，保留 metadata 中的主体结构，并把提示词放进顶层 input。不能只提交 metadata.subjects：Responses 仍要求提取到文字或顶层/input 图片，详见Responses 创建。

参考：官方参考生视频的主体调用。

Request

请求

/ent/v2/reference2video

Body

必填

Bodyobject

modelstring必填

模型名称可选值：viduq3-mix、viduq3、viduq2-pro、viduq2、viduq1、vidu2.0 - viduq3-mix：画面质感强，支持智能切镜，支持音画同出，动态效果好，均衡性最强 - viduq3：支持智能切镜，支持音画同出，多机位的一致性更出色 - viduq2-pro：支持参考视频，支持视频编辑，视频替换 - viduq2：动态效果好，生成细节丰富 - viduq1：画面清晰，平滑转场，运镜稳定 - vidu2.0：生成速度快

auto_subjectsstring

- 是否使用智能主体库能力，默认false，可选值 true、false - true：使用智能主体库能力。 - false：不使用智能主体库能力。

subjectsarray<object>必填

图片主体信息支持1-7个主体，主体图片共1 ～ 7张

元素object

namestring必填

用户指定的主体名称（name），生成时可以通过[@name]的方式使用，例如：[@图1]

imagesarray<string>

临时主体图片，最多3张图片注1：支持传入图片 Base64 编码或图片URL（确保可访问）注2：图片支持 png、jpeg、jpg、webp格式注3：图片像素不能小于 128*128，且比例需要小于1:4或者4:1 注4：请注意，http请求的post body不超过20MB，且编码必须包含适当的内容类型字符串，例如： data:image/png;base64,{base64_encode}

元素string

videosarray<string>

临时主体视频，最多1个5秒视频注1：仅参考生viduq2-pro模型支持使用视频主体注2：最多支持上传 1个5秒的视频注3：视频支持 mp4、avi、mov格式注4：视频像素不能小于 128*128，且比例需要小于1:4或者4:1 注5：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串，例如： data:video/mp4;base64,{base64_encode}

元素string

voice_idstring

音色ID用来决定视频中的声音音色，为空时系统会自动推荐，可选枚举值参考列表：新音色列表：https://shengshu.feishu.cn/sheets/EgFvs6DShhiEBStmjzccr5gonOg

server_idstring

通过创建主体API获取的主体id 注：不传server_id时，为临时主体，系统不保存

promptstring必填

文本提示词生成视频的文本描述。注：字符长度不能超过 2000 个字符

audiostring

是否使用音视频直出能力，默认false，可选值 true、false - true：使用音视频直出能力。 - false：不使用音视频直出能力。注：viduq3 模型默认值为true

durationnumber

视频时长参数，默认值依据模型而定 viduq3：默认5秒，可选：3 - 16 viduq2-pro、viduq2：默认5秒，可选：1 - 10 viduq1：默认5秒，可选：5 vidu2.0：默认4秒，可选：4

seedstring

随机种子当默认不传或者传0时，会使用随机数替代手动设置则使用设置的种子

aspect_ratiostring

比例参数，q2、q3模型支持任意比例或 auto 默认 16:9，可选值如下：1:1、9:16、16:9、3:4、4:3 auto：根据输入图或视频自动推荐

resolutionstring

分辨率参数，默认值依据模型和视频时长而定： viduq3（3-16秒）：默认 720p, 可选：540p、720p、1080p viduq2-pro、viduq2 （1-10秒）：默认 720p, 可选：540p、720p、1080p viduq1 （5秒）：默认 1080p, 可选：1080p vidu2.0 （4秒）：默认 360p, 可选：360p、720p

movement_amplitudestring

运动幅度默认 auto，可选值：auto、small、medium、large 注：使用q2、q3系列模型时该参数不生效

payloadstring

透传参数不做任何处理，仅数据传输注：最多 1048576个字符

watermarkstring

是否添加水印 - true：添加水印； - false：不添加水印；注1：目前水印内容为固定，内容由AI生成，默认不加注2：您可以通过watermarked_url参数查询获取带水印的视频内容，详情见查询任务接口

wm_positionstring

水印位置，表示水印出现在图片的位置，可选项为： 1：左上角 2：右上角 3：右下角 4：左下角默认为：3

wm_urlstring

水印内容，此处为图片URL 不传时，使用默认水印：内容由AI生成

meta_datastring

元数据标识，json格式字符串，透传字段，您可以自定义格式或使用示例格式，示例如下： { "Label": "your_label","ContentProducer": "yourcontentproducer","ContentPropagator": "your_content_propagator","ProduceID": "yourproductid", "PropagateID": "your_propagate_id","ReservedCode1": "yourreservedcode1", "ReservedCode2": "your_reserved_code2" } 该参数为空时，默认使用vidu生成的元数据标识

callback_urlstring

Callback 协议需要您在创建任务时主动设置 callback_url，请求方法为 POST，当视频生成任务有状态变化时，Vidu 将向此地址发送包含任务最新状态的回调请求。回调请求内容结构与查询任务API的返回体一致回调返回的"status"包括以下状态： - processing 任务处理中 - success 任务完成（如发送失败，回调三次） - failed 任务失败（如发送失败，回调三次） Vidu采用回调签名算法进行认证，详情见：回调签名算法

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY
`Content-Type`	Header	string	否	-	application/json

请求示例application/json

curl --fail-with-body "https://top.qingyuntop.ai/v1/videos" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "viduq2",
  "prompt": "@astronaut 在月球表面缓缓行走，保持服装和人物外观一致。",
  "seconds": 5,
  "resolution": "720p",
  "metadata": {
    "action": "reference_to_video",
    "subjects": [
      {
        "name": "astronaut",
        "images": [
          "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png"
        ]
      }
    ],
    "aspect_ratio": "16:9"
  }
}'

Response

返回响应 `200`

HTTP 响应

响应 200object

task_idstring必填

typestring必填

statestring必填

modelstring必填

stylestring必填

promptstring必填

imagesarray<string>必填

元素string

durationinteger必填

seedinteger必填

aspect_ratiostring必填

resolutionstring必填

movement_amplitudestring必填

created_atstring必填

creditsinteger必填

payloadstring必填

cus_priorityinteger必填

off_peakboolean必填

watermarkboolean必填

is_recboolean必填

wm_positionstring必填

wm_urlstring必填

meta_datastring必填

client_request_idstring必填

响应示例json

{
  "task_id": "911084878697623552",
  "type": "character2video",
  "state": "created",
  "model": "viduq2",
  "style": "general",
  "prompt": "一只可爱的@cat在草地上奔跑，阳光明媚，画面温馨",
  "images": [
    "https://picx.zhimg.com/v2-4911df093b40ee5511938a1ac2a5cdc4_r.jpg"
  ],
  "duration": 5,
  "seed": 1830691647,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "movement_amplitude": "auto",
  "created_at": "2026-01-20T06:37:57.371761937Z",
  "credits": 45,
  "payload": "",
  "cus_priority": 0,
  "off_peak": false,
  "watermark": false,
  "is_rec": false,
  "wm_position": "unspecified",
  "wm_url": "",
  "meta_data": "",
  "client_request_id": ""
}

Vidu 参考生视频（主体调用）

功能与模型

1. 设置鉴权

2. 调用模型生成

代码示例

查询与下载

请求

Body

路径、查询与 Header 参数

返回响应 200

返回响应 `200`