POST/ent/v2/reference2video

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

直接提供参考图片，让模型保持主体外观和视觉风格；这些图片不被指定为视频首帧或尾帧。

API Key application/json

功能与模型

官方当前非主体参考型号为 viduq3-mix、viduq3-turbo、viduq3-pro、viduq2-pro、viduq2、viduq1 和 vidu2.0。下表只列当前插件离线核验的可执行组合；Q2 Pro 的视频参考、编辑和替换分支必须由当前 Key 与本站路由分别确认，不能仅靠添加 videos 字段启用。

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

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

参考图片通常为 1–7 张；具体模型的图片/视频条件、数量和时长以官方动作页面为准。vidu2.0 在当前插件核验的参考接口只允许 4 秒、360p/720p，不能沿用图生的 8 秒组合。

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"，特别是只有 1 或 2 张参考图时。

参数	类型	说明
`model`	string	必填。当前插件离线核验为 viduq2、viduq1、vidu2.0；官方参考生页面还列出 viduq3-mix、viduq3-turbo、viduq3、viduq2-pro。Q2 Pro 的视频参考/编辑条件不能套用图片参考示例，新增型号需先由 GET /v1/models 确认开放。
`images`	string[]	本页必填，顶层数组，1–7 张参考图。即使只有 1 或 2 张，也必须显式设置 metadata.action=reference_to_video。
`metadata.videos`	string[]	本页不支持视频参考。请使用图片参考；不要直接改为 viduq2-pro 或在本请求中添加参考视频。
`prompt`	string	必填，最多 5000 字符。描述参考主体要执行的动作、场景和镜头。
`seconds`	integer	选填；本站优先使用 seconds（单位：秒），不要同时设置 duration。模型组合见本页表格。
`metadata.seed`	integer	选填，放入 metadata。整数随机种子；省略时由上游随机生成，不保证跨任务像素级一致。
`metadata.aspect_ratio`	string	选填，放入 metadata。默认 16:9；支持 16:9、9:16、1:1；viduq2 另支持 3:4、4:3。
`resolution`	string	选填。显式使用本页允许的档位；不表示画面比例。
`metadata.movement_amplitude`	string	选填，放入 metadata。auto（默认）、small、medium、large；viduq2 不生效。
`metadata.bgm`	boolean	选填，放入 metadata，默认 false。true 为视频添加背景音乐；viduq2 的 9/10 秒任务不生效。不是独立音频生成。
`metadata.payload`	string	选填，放入 metadata。业务透传字符串，最多 1048576 字符；统一视频结果不会承诺回显，关联任务请自行保存返回 ID。
`metadata.off_peak`	boolean	选填，放入 metadata，默认 false。初次接入建议保持 false；当前文档不提供取消任务入口，不承诺官方直连的退款规则适用于本站。
`metadata.callback_url`	string	选填，上游回调地址，放入 metadata。不能用本站 API Key 验证厂商回调签名；建议先采用查询接口。详见状态码、错误与回调。

图片每边至少 128 像素；建议宽高比位于 1:4 到 4:1 之间。支持 PNG、JPEG/JPG、WebP。URL 图片不超过 50MB；Base64 解码后须小于 10MB，编码字符串包含 data:image/...;base64, 前缀。

代码示例

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

示例故意只用 1 张图，并明确指定参考动作。

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": "保持参考图中宇航员的外观，宇航员在月球表面漫步，镜头平稳跟随。",
  "images": [
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png"
  ],
  "seconds": 5,
  "resolution": "720p",
  "metadata": {
    "action": "reference_to_video",
    "aspect_ratio": "16:9"
  }
}'

查询与下载

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

省略 action 时，单张图片会按图生、两张图片会按首尾帧自动判断；因此参考场景必须显式写 reference_to_video。视频参考与编辑不在当前插件离线示例范围内，不要通过 metadata.model、videos 或 remixGenerate 尝试打开。

参考：官方参考生视频。

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：生成速度快

imagesarray<string>

图像参考支持多张图片，模型将以此参数中传入的图片中的主题为参考生成具备主体一致的视频，各模型版本可参考图片数量不同，具体要求如下注1：viduq3、viduq2、viduq1、vidu2.0系列模型支持上传1～7张图片注2：使用viduq2-pro模型时，如果不上传视频，则支持上传1-7张图，如果上传视频则支持1-4张图注3：支持传入图片 Base64 编码或图片URL（确保可访问）注4：图片支持 png、jpeg、jpg、webp格式注5：图片像素不能小于 128*128，且比例需要小于1:4或者4:1 注6：请注意，http请求的post body不超过20MB，且编码必须包含适当的内容类型字符串，例如： data:image/png;base64,{base64_encode}

元素string

videosarray<string>

视频参考支持上传1～2个视频，模型将以此参数中传入的视频作为参考，生成具备主体一致的视频。注1：仅viduq2-pro模型支持该参数注2：使用视频参考功能时，最多支持上传 1个8秒视频或 2个5秒视频注3：视频支持 mp4、avi、mov格式注4：视频像素不能小于 128*128，且比例需要小于1:4或者4:1，且大小不超过100M。注5：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串，例如：data:video/mp4;base64,{base64_encode}

元素string

soundsarray<string>

音频参考支持上传1～7个音频，模型将以此参数中传入的音频作为参考，生成具备主体一致的视频。注1：使用音频参考功能时，最多支持上传 7个音频，每个音频时长最多20s 注2：音频支持 mp3格式注3：每个音频文件大小不超过50M。注4：请注意，base64 decode之后的字节长度需要小于20M，且编码必须包含适当的内容类型字符串，例如： data:video/mp3;base64,{base64_encode} 注：目前暂不支持，仅提前预留该参数

元素string

promptstring必填

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

bgmstring

是否为生成的视频添加背景音乐。默认：false，可选值 true 、false - 传 true 时系统将从预设 BGM 库中自动挑选合适的音乐并添加；不传或为 false 则不添加 BGM。 - BGM不限制时长，系统根据视频时长自动适配 - 该参数在q2系列模型的duration为 9秒或 10秒时不生效 - 该参数在q3系列模型中不生效

audiostring

是否使用音视频直出能力，默认为true，枚举值为： - false：不需要音视频直出，输出静音视频 - true：需要音画同步，输出声音的视频（包括台词和音效）注：非主体调用时，仅q3模型支持该参数

durationnumber

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

seednumber

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

aspect_ratiostring

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

resolutionstring

分辨率参数，默认值依据模型和视频时长而定： viduq3-mix（1-16秒）：默认 720p, 可选：720p、1080p 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": "保持参考图中宇航员的外观，宇航员在月球表面漫步，镜头平稳跟随。",
  "images": [
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png"
  ],
  "seconds": 5,
  "resolution": "720p",
  "metadata": {
    "action": "reference_to_video",
    "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`