Vidu 参考生视频 API 文档

按主体或参考图/视频生成一致性视频。

官方参数详见 Vidu 官方文档。

服务商支持

渠道	说明
Vidu 官方	默认；主体库模式（subjects[].server_id 非空）始终走官方

路由说明：请求体含 subjects[].server_id（主体库 id / vidu_sub_* / elem_ap_*）时，proxy 在路由阶段强制官方。

创建任务

网络协议	请求地址	请求方法	请求格式	响应格式
https	/videos/vidu/reference2video	POST	application/json	application/json

请求头

字段	值	描述
Content-Type	application/json	数据交换格式
Authorization	Bearer	aiping 平台鉴权

请求体参数

参数名	类型	必填	说明
model	string	是	如 viduq3、viduq2、viduq2-pro
prompt	string	是	可用 @主体name 引用 subjects
subjects	array	条件	主体模式：每项含 name、images/videos、voice_id、server_id
images	array	条件	非主体模式：参考图 1～7 张
videos	array	条件	非主体模式：参考视频（viduq2-pro）
duration	int	否	时长
aspect_ratio	string	否	比例
resolution	string	否	分辨率
audio	bool	否	音视频直出
off_peak	bool	否	错峰模式
extra_body.provider	object	否	路由，见 路由策略

主体库：subjects[].server_id 可为 Vidu 官方主体 id，或 aiping 统一主体 id（elem_ap_*，提交前由 proxy 解析）。须先通过 subjects.md 创建，且调用方 API Key 与创建时一致（平台注入的 user_id 须为属主）。带 server_id 时自动走官方。

详见 subjects.md。

查询任务（标准异步）

提交后使用 task-query.md 中的统一查询接口：

网络协议	请求地址	请求方法
https	/videos/vidu/tasks/{task_id}/creations	GET

响应为 Vidu 官方 creations 形态（state、creations[].url、credits 等）。

请求示例

subjects 临时主体模式

{
  "model": "viduq2",
  "subjects": [
    {
      "name": "hero",
      "images": ["https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png"],
      "voice_id": ""
    }
  ],
  "prompt": "@hero 转身看向镜头，背景出现柔和光晕，整体保持主体一致性",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": false,
  "seed": 0,
  "off_peak": false,
  "watermark": false,
  "extra_body": {
    "provider": { "only": ["Vidu"] }
  }
}

images 参考图模式

{
  "model": "viduq3-turbo",
  "images": [
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/image2video.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/scene-template/hug.jpeg"
  ],
  "prompt": "参考图中的人物保持一致，在室内空间中自然移动，镜头轻微环绕",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "audio": false,
  "seed": 0,
  "off_peak": false,
  "watermark": false,
  "payload": "test-vidu-reference2video-images"
}

返回结构示例

{
  "task_id": "string",
  "state": "created",
  "model": "viduq2",
  "prompt": "@hero 转身看向镜头，背景出现柔和光晕，整体保持主体一致性",
  "duration": 5,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "off_peak": false,
  "watermark": false,
  "credits": 0,
  "created_at": "2025-01-01T00:00:00Z",
  "aiping_id": "string"
}

注意事项

1. 参数取值范围、模型能力详见 Vidu 官方文档。
2. 用户隔离：主体库跨用户访问会被拒绝（列表过滤 / 更新 400 / reference 解析失败）；测试与生产均应以 不同 API Key 区分用户。
3. ViduQ2 错峰价格为正常生成价格的一半；如果积分存在小数，则向上取整。
4. 参考生视频开启音视频直出功能时，会在对应任务基础上多消耗 15 积分。
5. 积分与人民币换算比例为：1 积分 = 0.03125 元。