多主体多参考图 / 视频参考

参考图生成视频

多主体生成用于在同一个视频中引入多张参考图，例如人物、宠物、商品和背景。通过 ref_name 可以在 prompt 中精确指代不同参考图。

能力示例视频

接入流程

上传参考图片 -> 组装 image_references -> 在 prompt 中引用 @ref_name -> 发起生成任务 -> 查询任务状态

接口地址

请求参数

参数	类型	是否必填	说明
`image_references`	array	是	参考图数组；最少 1 张，最多 7 张。
`image_references[].img_id`	integer	是	上传图片后获得的图片 ID
`image_references[].type`	string	否	`subject`（主体参考，如人物、动物、产品；建议一张图只包含一个清晰主体）或 `background`（场景/背景参考，用于约束环境、空间和整体氛围。）；仅`v5`以下版本支持。
`image_references[].ref_name`	string	否	参考图名称，上限30 个 Unicode（区分大小写）；可在 prompt 中用 `@ref_name` 引用
`prompt`	string	是	生成提示词；引用名称后需要加空格，例如 `@dog runs` 最高支持 5000 characters
`model`	string	是	模型名称：`c1`、`v6`、`v5.6`、`v5`。新接入优先使用 `c1` 或 `v6`
`duration`	integer	是	视频时长：`c1` / `v6` 支持 `1~15` 秒；`v5.6` 支持 `5` / `8` / `10` 秒；`v5` 支持 `5` / `8` 秒。
`quality`	string	是	`360p`、`540p`、`720p`、`1080p`
`aspect_ratio`	string	是	画幅比例；`c1` / `v6` 支持 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`、`2:3`、`3:2`、`21:9`；`v5.6` / `v5` 支持 `16:9`、`9:16`、`4:3`、`3:4`、`1:1`。
`generate_audio_switch`	boolean	否	是否生成音频；仅`c1`、`v6`、`v5.6` 支持，`v5` 使用旧版音效字段。

最小请求示例

{
  "image_references": [
    {
      "img_id": 123456,
      "ref_name": "dog"
    },
    {
      "img_id": 123457,
      "ref_name": "room"
    }
  ],
  "prompt": "@dog plays in @room with soft cinematic lighting",
  "model": "v6",
  "duration": 5,
  "quality": "720p",
  "aspect_ratio": "16:9"
}

响应字段

字段	类型	说明
`ErrCode`	integer	错误码，`0` 表示成功
`ErrMsg`	string	错误信息，成功时通常为 `Success`
`Resp.video_id`	integer	视频任务 ID，后续用于查询任务状态
`Resp.credits`	integer	本次任务实际消耗点数

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 123456,
    "credits": 60
  }
}

下一步

调用「查询任务状态」接口，通过返回的 video_id 获取生成进度和最终视频 URL。

注意事项

prompt 中引用的名称必须与 ref_name 完全一致。

@ref_name 后必须有空格，方便模型识别引用对象。

多主体适合解决角色或主体一致性问题，但素材质量会直接影响结果。

全能参考生成视频

视频参考用于让 V6 模型理解参考视频中的主体、动作、场景、运镜、节奏和画面风格，并结合提示词生成新视频。适用于主体替换、视频复刻、动作模仿和镜头风格迁移等场景。

适用场景

场景	说明
动作与节奏参考	参考原视频中的人物动作、运动节奏和时间关系
运镜与构图参考	复用镜头运动、景别变化和画面构图
场景与风格参考	参考环境、光影、色彩和整体视觉风格
主体替换与视频复刻	保留原视频的动作或镜头结构，同时根据提示词修改主体和内容

接入流程

上传参考视频 -> 获取 media_id -> 填入 video_references[].video_media_id
-> 设置 model=v6、reference_mode=omni、duration=0
-> 发起生成任务 -> 查询任务状态或等待 Webhook 回调 -> 获取视频 URL

接口地址

前置步骤

先调用上传资源接口，将本地参考视频以 multipart/form-data 上传并获取 Resp.media_id：

上传成功响应示例：

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "media_id": 123456789,
    "media_type": "video",
    "url": "https://media.pixverseai.cn/example.mp4"
  }
}

上传接口返回字段名为 media_id；调用视频参考接口时，应将该值填入 video_references[].video_media_id。

请求参数

参数	类型	是否必填	枚举值 / 示例	说明
`video_references`	array	是	1～2 项	视频参考数组；所有参考视频总时长不得超过 15 秒
`video_references[].source_video_id`	integer	条件必填	`123456789`	PixVerse API 生成视频返回的 `video_id`；与 `video_media_id` 二选一
`video_references[].video_media_id`	integer	条件必填	`123456789`	上传资源接口返回的 `media_id`；与 `source_video_id` 二选一
`video_references[].ref_name`	string	否	`motion`	参考视频名称；如填写，可在 prompt 中使用 `@motion` 精确引用
`image_references`	array	否	最多 10 项	V6 Omni 模式可同时使用参考图片；图片与视频按各自数量限制传入
`image_references[].img_id`	integer	条件必填	`123456`	上传图片接口返回的 `img_id`
`image_references[].ref_name`	string	否	`character`	图片参考名称；如填写，可在 prompt 中使用 `@character` 引用
`reference_mode`	string	是	`omni`	使用视频参考时固定填写 `omni`
`prompt`	string	是	`参考 @motion 的动作和运镜，生成新的电影感视频`	描述需要参考和修改的内容；`@ref_name` 后应保留空格
`model`	string	是	`v6`	视频参考当前仅支持 `v6`
`duration`	integer	是	`0`	有视频参考时固定填写 `0`，系统自动取最长参考视频的时长, 如果是图片参考, 可支持 1~15
`quality`	string	是	`360p`、`540p`、`720p`、`1080p`	输出分辨率
`aspect_ratio`	string	是	`auto`、`16:9`、`9:16`、`4:3`、`3:4`、`1:1`、`2:3`、`3:2`、`21:9`	V6 Omni 模式支持 `auto`
`generate_audio_switch`	boolean	否	`true`、`false`	是否生成音频；不传时以服务端当前默认行为为准
`seed`	integer	否	`123456789`	随机种子；相同参数和种子不保证生成结果完全一致

组合校验规则

规则	要求
视频来源	每个 `video_references[]` 元素必须且只能填写 `source_video_id`、`video_media_id` 之一
模型与模式	有视频参考时必须同时设置 `model=v6` 和 `reference_mode=omni`
时长	有视频参考时 `duration` 必须为 `0`；参考视频总时长不得超过 15 秒
数量	每次最多 2 个参考视频；V6 Omni 模式最多支持 10 张参考图片和 2 个参考视频
引用名称	prompt 中的 `@ref_name` 必须与参考项的 `ref_name` 完全一致，且引用名称后应保留空格

最小请求示例

{
  "video_references": [
    {
      "video_media_id": 123456789
    }
  ],
  "prompt": "参考视频中的人物动作、节奏和镜头运动，生成一段新的电影感视频",
  "model": "v6",
  "reference_mode": "omni",
  "duration": 0,
  "quality": "720p",
  "aspect_ratio": "16:9"
}

响应字段

字段	类型	是否必返	说明
`ErrCode`	integer	是	业务错误码，`0` 表示请求成功
`ErrMsg`	string	是	响应信息
`Resp.video_id`	integer	成功时是	视频任务 ID，用于查询任务状态
`Resp.credits`	integer	成功时是	本次任务实际消耗点数

响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "video_id": 123456789,
    "credits": 18
  }
}

注意事项

HTTP 状态码为 200 不等于业务成功，仍需检查 ErrCode=0。

参考视频的清晰度、主体完整度、动作连续性和镜头稳定性会直接影响结果。

每个参考项内不要同时填写 source_video_id 和 video_media_id。

有视频参考时不要遗漏 reference_mode=omni，也不要将 duration 设置为非 0。

参考视频总时长超过 15 秒、视频数量超过 2 个或使用非 V6 模型时，请求会进入参数校验失败。

多主体多参考图 / 视频参考

参考图生成视频#

能力示例视频#

接入流程#

接口地址#

请求参数#

最小请求示例#

响应字段#

响应示例#

下一步#

注意事项#

全能参考生成视频#

适用场景#

接入流程#

接口地址#

前置步骤#

请求参数#

组合校验规则#

最小请求示例#

响应字段#

响应示例#

注意事项#

请求参数

返回响应

参考图生成视频

能力示例视频

接入流程

接口地址

请求参数

最小请求示例

响应字段

响应示例

下一步

注意事项

全能参考生成视频

适用场景

接入流程

接口地址

前置步骤

请求参数

组合校验规则

最小请求示例

响应字段

响应示例

注意事项