主体替换 Swap

主体替换用于把视频中的指定人物、物体或背景区域替换为一张新的目标图片。该能力需要先调用 Mask 接口识别可替换区域，再将选中的 mask_id 传入 Swap 生成接口。

前提条件

开始调用前，请确认以下条件均已满足：

项目	要求	获取方式
API 鉴权	有效的 `API-KEY`	在拍我AI开放平台控制台获取。
请求追踪 ID	每次请求携带新的 `Ai-trace-id`	使用 UUID。不要在 Mask、上传图片、Swap 等不同请求之间重复使用同一个值。
账户状态	API 服务可用且账户点数充足	在控制台查看订阅或点数余额。
源视频	`source_video_id` 或 `video_media_id` 二选一	PixVerse 生成视频返回 `video_id`；上传视频返回 `media_id`。
替换图片	已取得 `img_id`	调用 `POST /openapi/v2/image/upload` 上传目标图片。
Mask 结果	已取得与源视频对应的 `keyframe_id` 和 `mask_id`	调用 `POST /openapi/v2/video/mask/selection`。

源视频二选一

视频来源	Mask 和 Swap 中填写的字段	值的来源
PixVerse API 生成的视频	`source_video_id`	视频生成接口返回的 `Resp.video_id`
用户上传的外部视频	`video_media_id`	`POST /openapi/v2/media/upload` 返回的 `Resp.media_id`

同一次主体替换流程中，Mask 与 Swap 请求必须使用完全相同的视频来源字段和值。例如，Mask 使用 video_media_id: 123，Swap 也必须使用 video_media_id: 123，不能改成 source_video_id。

素材限制

源视频：

项目	当前要求
最大分辨率	最长边不超过 `1920px`
最大时长	`30s`
编码	`H.264` 或 `H.265`
常见容器格式	`mp4`、`mov`；上传接口还支持 `webm`
文件大小	`100MB`之内

替换图片：

项目	当前要求
格式	`jpg`、`jpeg`、`png`、`webp`
最大文件大小	`20MB`
最大尺寸	最长边不超过 `10000px`

接入流程

准备源视频
  -> 上传替换图片并取得 img_id
  -> 调用 Mask 接口
  -> 根据 keyframe_url、mask_name、mask_url 选择目标区域
  -> 保存对应的 keyframe_id 和 mask_id
  -> 调用 Swap 接口
  -> 使用 video_id 查询任务状态

第一步：上传替换图片

上传本地文件：

上传成功后保存 Resp.img_id。Swap 请求只填写 img_id，不填写图片名称或 img_url。

第二步：生成 Mask

请求 Header

Header	类型	是否必填	枚举值 / 示例	说明
`API-KEY`	string	是	`your-api-key`	必须放在 Header 中，不要放入 URL Query。
`Ai-trace-id`	string	是	`550e8400-e29b-41d4-a716-446655440002`	本次 Mask 请求的唯一 UUID。
`Content-Type`	string	是	`application/json`	固定填写 `application/json`。

Body 参数

参数	类型	是否必填	枚举值 / 示例	说明
`source_video_id`	integer	条件必填	`123456789`	PixVerse 生成的视频 ID。与 `video_media_id` 必须且只能填写一个。
`video_media_id`	integer	条件必填	`987654321`	上传视频接口返回的 `media_id`。与 `source_video_id` 必须且只能填写一个。
`keyframe_id`	integer	否	`1`	要识别的关键帧序号；省略时默认为 `1`。有效范围为第 `1` 帧至视频最后一帧，0 表示自动选择，正数按帧率换算截帧时间

最小请求示例：PixVerse 生成视频

{
  "source_video_id": 123456789,
  "keyframe_id": 1
}

最小请求示例：上传视频

{
  "video_media_id": 987654321,
  "keyframe_id": 1
}

完整 cURL 示例

Mask 响应字段

字段	类型	说明	后续是否需要填写
`ErrCode`	integer	业务错误码，`0` 表示成功。	否
`ErrMsg`	string	错误信息；成功时通常为 `Success`。	否
`Resp.keyframe_id`	integer	服务端实际使用的关键帧 ID。	是，原样传入 Swap 的 `keyframe_id`。
`Resp.keyframe_url`	string	关键帧预览地址。	否，仅用于确认当前帧。
`Resp.credits`	integer	本次 Mask 请求消耗点数，以实际响应为准。	否
`Resp.mask_info`	array	当前关键帧识别出的候选区域列表。	否
`Resp.mask_info[].mask_id`	string	候选区域 ID。	是，选择一个后原样传入 Swap 的 `mask_id`。
`Resp.mask_info[].mask_name`	string	候选区域名称，例如人物、物体或背景。	否，仅用于辅助选择。
`Resp.mask_info[].mask_url`	string	候选区域 Mask 预览地址。	否，不能作为 Swap 的请求参数。

Mask 响应示例

{
  "ErrCode": 0,
  "ErrMsg": "Success",
  "Resp": {
    "keyframe_id": 1,
    "keyframe_url": "https://media.pixverseai.cn/example/keyframe.png",
    "credits": 2,
    "mask_info": [
      {
        "mask_id": "0",
        "mask_name": "person",
        "mask_url": "https://media.pixverseai.cn/example/person-mask.png"
      },
      {
        "mask_id": "1",
        "mask_name": "background",
        "mask_url": "https://media.pixverseai.cn/example/background-mask.png"
      }
    ]
  }
}

如何选择 Mask

使用 keyframe_url 确认识别的是预期视频帧。

遍历 mask_info，结合 mask_name 和 mask_url 判断要替换的区域。

保存该项的 mask_id。

Swap 请求必须同时复用本次 Mask 对应的源视频和 Resp.keyframe_id。

如果 mask_info 为空，或无候选区域时返回业务错误 ErrApiSwapMarkListEmpty。

第三步：创建 Swap 任务

请求 Header

Header	类型	是否必填	枚举值 / 示例	说明
`API-KEY`	string	是	`your-api-key`	必须与当前环境和账号匹配。
`Ai-trace-id`	string	是	`550e8400-e29b-41d4-a716-446655440003`	本次 Swap 请求使用新的 UUID，不复用 Mask 请求的值。
`Content-Type`	string	是	`application/json`	固定填写 `application/json`。

Body 参数

参数	类型	是否必填	枚举值 / 示例	说明
`source_video_id`	integer	条件必填	`123456789`	与 Mask 请求中的 `source_video_id` 完全一致；与 `video_media_id` 二选一。
`video_media_id`	integer	条件必填	`987654321`	与 Mask 请求中的 `video_media_id` 完全一致；与 `source_video_id` 二选一。
`keyframe_id`	integer	是	`1`	原样填写 Mask 响应中的 `Resp.keyframe_id`。
`mask_id`	string	是	`"0"`	原样填写所选 `Resp.mask_info[].mask_id`，注意按字符串传递。
`img_id`	integer	是	`246801357`	上传替换图片返回的 `Resp.img_id`。
`quality`	string	是	`360p`、`540p`、`720p`	输出视频清晰度。

参数对应规则

下面四项必须属于同一次完整链路：

字段	来源
`source_video_id` 或 `video_media_id`	Mask 请求中使用的同一字段和值
`keyframe_id`	Mask 响应 `Resp.keyframe_id`
`mask_id`	同一 Mask 响应中选中的 `Resp.mask_info[].mask_id`
`img_id`	上传替换图片响应 `Resp.img_id`

不要自行构造 mask_id，也不要把 mask_name、mask_url 或 keyframe_url 填入 Swap 请求。

最小请求示例：PixVerse 生成视频

{
  "source_video_id": 123456789,
  "keyframe_id": 1,
  "mask_id": "0",
  "img_id": 246801357,
  "quality": "540p"
}

最小请求示例：上传视频

{
  "video_media_id": 987654321,
  "keyframe_id": 1,
  "mask_id": "0",
  "img_id": 246801357,
  "quality": "540p"
}

完整 cURL 示例

Swap 响应字段

字段	类型	说明
`ErrCode`	integer	业务错误码，`0` 表示成功。
`ErrMsg`	string	错误信息；成功时通常为 `Success`。
`Resp.video_id`	integer	主体替换任务 ID，用于查询生成状态。
`Resp.credits`	integer	本次生成任务消耗点数，以实际响应为准。

成功响应示例

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

HTTP 状态码为 200 只表示请求已到达服务端，仍需检查 ErrCode 是否为 0。

第四步：查询任务状态

创建成功后，使用 Swap 响应中的 Resp.video_id 调用：

常见错误与排查

问题	常见原因	处理建议
Mask 请求参数错误	同时填写或同时缺少 `source_video_id`、`video_media_id`	两者必须且只能填写一个。
`mask_info` 为空	当前帧没有识别出可替换区域	更换 `keyframe_id` 后重新请求。
Swap 提示 Mask 无效	源视频、`keyframe_id` 或 `mask_id` 与 Mask 请求不对应	原样复用同一次 Mask 调用产生的字段组合。
替换图片无效	将 `img_url` 当成 `img_id`，或图片上传失败	重新上传图片，并填写响应中的整数 `Resp.img_id`。

注意事项

Mask 与 Swap 的视频来源必须完全一致。

Swap 的 keyframe_id 和 mask_id 必须来自同一次 Mask 响应。

mask_id 是字符串；不要改成整数，也不要自行拼接。

mask_url、keyframe_url 仅用于预览，不是 Swap 请求参数。

img_id 来自图片上传接口；本接口不使用 img_ids。

不要同时填写 source_video_id 和 video_media_id。

每个上传、Mask、Swap 和状态查询请求都应使用新的 Ai-trace-id。

API Key 属于敏感凭证，不要写入 URL、前端代码、截图或公开日志。

目前不支持直接传入外部 mask_url。mask_url 仅用于预览 Mask 识别结果，真正创建任务时必须传 mask_id。

主体替换 Swap