Vidu 请求参数与媒体输入

区分 Q2、Q3 与 Q4 Preview 的时长、分辨率、图片输入、音频和原生扩展参数。

本页按接口概览中的已开放模型说明常用参数。请求正文中的 model 使用准确的小写模型名；不同模型、操作的参数能力不同，不应直接互换。

时长、分辨率与声音

模型	`duration`，整数秒	本系列使用的 `resolution`
`viduq2`、`viduq2-pro`、`viduq2-turbo`	1–10，默认 5	`540p`、`720p`、`1080p`，默认 `720p`
`viduq2-pro-fast`	1–10，默认 5	`720p`、`1080p`，默认 `720p`
`viduq3-pro`、`viduq3-turbo`	1–16，默认 5	`540p`、`720p`、`1080p`，默认 `720p`
`viduq4-preview`（可用性待确认）	3–16，默认 5	`540p`、`720p`、`1080p`、`2K`、`4K`，默认 `720p`

resolution 是模型的清晰度档位，输出像素还与画面比例及模型尺寸对齐有关。不要将 540p 视作所有比例下都严格输出 540 像素高。

Q3 与 Q4 的 audio 默认 true，false 输出静音视频。Q2 文生的音频默认开启，Q2 图生与参考生默认关闭；使用时建议显式传值。首尾帧接口的声音参数依模型而定，不直接套用图生的 audio 约定。音频及提示词扩写等选项可能改变计费，请以模型价格为准。

选择图片输入方式

操作	路径	图片含义
图生视频	`/ent/v2/img2video`	`images` 数组中的一张首帧图
首尾帧视频	`/ent/v2/start-end2video`	`images` 依次为首帧、尾帧，共两张
参考生视频	`/ent/v2/reference2video`	`images` 作为参考素材；数量和主体能力依模型而定

Q2 图片参考使用 1–7 张图片，并提供非空 prompt。本系列只说明图片参考，不包含视频参考或视频编辑。

使用可公开直接下载的图片 URL，不能填写本地文件路径或需要登录的网页地址。支持的图片格式包含 PNG、JPEG/JPG 和 WEBP；也可使用完整的图片 data URI，例如 data:image/png;base64,...。图片尺寸、比例和请求体限制按对应模型及操作校验。

Q3 图生视频

将 images 替换为真实素材 URL，发送至 POST /ent/v2/img2video：

{
  "model": "viduq3-pro",
  "images": ["https://example.com/first-frame.png"],
  "prompt": "镜头缓慢拉远，参考图中的人物抬手打招呼",
  "duration": 5,
  "resolution": "720p",
  "audio": false,
  "is_rec": false,
  "seed": 0,
  "watermark": false
}

Q3 首尾帧视频

发送至 POST /ent/v2/start-end2video；图片顺序决定首尾画面：

{
  "model": "viduq3-turbo",
  "images": ["https://example.com/first.png", "https://example.com/last.png"],
  "prompt": "镜头平稳推进，从花苞过渡到盛开的花朵",
  "duration": 5,
  "resolution": "720p",
  "is_rec": false,
  "watermark": false
}

Q2 参考生视频

viduq2 的参考素材必须发送至 POST /ent/v2/reference2video，不要将单张参考图误发到图生路径：

{
  "model": "viduq2",
  "images": ["https://example.com/teapot.png"],
  "prompt": "保持参考图中茶壶的外观，让它位于阳光照耀的木桌上，镜头缓慢环绕",
  "duration": 5,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "audio": false,
  "watermark": false
}

Q4 Preview 图生参数

以下根据 Q4 Preview 官方图生接口说明协议；当前生产可用性待确认，不能直接将 Q2 / Q3 的可用性推及 Q4。

images 必填且只接受一张首帧图，单图不超过 50 MB；HTTP body 小于 20 MB。Base64 编码会增大正文，优先使用 URL。
prompt 可选，最多 20,000 字符；is_rec 官方默认 true，可显式传 false。
duration 为 3–16 的整数；resolution、audio 见上表。
seed 省略或为 0 时随机；显式非零值用于指定种子。
watermark 建议显式设置，避免依赖默认值；wm_position 可选 1（左上）、2（右上）、3（右下）、4（左下），默认 3。

仅在渠道已开放时，将下列正文发送至 POST /ent/v2/img2video：

{
  "model": "viduq4-preview",
  "images": ["https://example.com/first-frame.png"],
  "prompt": "人物向镜头挥手，随后镜头缓慢上升",
  "duration": 5,
  "resolution": "720p",
  "audio": true,
  "is_rec": false,
  "seed": 0,
  "watermark": false
}

Q4 图生不能接收两张首尾帧图，也不能仅凭文字输入变为文生视频。官方另有参考生协议，是否可调用仍取决于所选模型和渠道。

原生扩展字段

字段	类型与用途
`aspect_ratio`	字符串，文生或参考生的画面比例；按具体模型选择，例如 `16:9`
`is_rec`	布尔值，提示词扩写；当前 Q3 请显式传 `false`
`off_peak`	布尔值，当前渠道仅允许省略或 `false`
`payload`	自定义透传字符串，最多 1,048,576 字符
`wm_url`	自定义水印图片 URL，按上游要求使用
`meta_data`	JSON 字符串，用于元数据标识；不是对象
`callback_url`	接收上游 POST 通知的 URL；回调可能使用上游任务 ID
`sounds`、`subjects`、`auto_subjects`	模型专属音频 / 主体参数，仅在对应模型和操作明确支持时使用

原生请求可以携带模型支持的扩展字段，包括 Q2 的 bgm 等；字段存在不代表每个模型都支持。统一视频格式只映射指定字段，需要完整原生参数时使用原生接口。

meta_data 示例：

{"meta_data": "{\"Label\":\"your-label\",\"ContentProducer\":\"your-company\"}"}

回调由上游发出，仅作为辅助通知。收到通知后，使用已保存的公共任务 ID 和 ModelSell API Key 主动查询确认结果；主要流程建议使用轮询。ModelSell 不提供本系列的回调接收地址。