视频编辑 Modify

视频编辑用于基于提示词修改已有视频内容。既支持仅使用普通 prompt 进行整体编辑，也支持结合参考图或 Mask 进行局部替换。

接入流程

准备源视频 -> 可选上传参考图 / 获取 Mask -> 编写编辑 prompt -> 发起 Modify 任务 -> 查询任务状态

接口地址

POST /openapi/v2/video/modify/generate

请求参数

参数	类型	是否必填	枚举值 / 限制	说明
`source_video_id`	integer	条件必填	PixVerse 视频 ID	与 `video_media_id` 必须且只能填写一个
`video_media_id`	integer	条件必填	上传视频 media ID	与 `source_video_id` 必须且只能填写一个
`prompt`	string	是	最长 5000 characters	普通文本可直接编辑；使用参考图或 Mask 时可引用 `@imgN`、`@selectionN`
`img_ids`	integer[]	条件必填	0-3 个	仅当 prompt 使用 `@imgN` 时填写；按占位符顺序传入上传图片 ID
`mask_ids`	string[]	条件必填	0-3 个	仅当 prompt 使用 `@selectionN` 时填写；传入 Mask 接口返回的 ID
`keyframe_id`	integer	条件必填	与 Mask 请求保持一致	使用 `mask_ids` 时必填；字段为单数
`quality`	string	是	`360p`、`540p`、`720p`	输出分辨率；不支持 `1080p`

最小请求示例：仅 Prompt

仅进行整体编辑时，不需要填写 img_ids、mask_ids 或 keyframe_id。

{
  "video_media_id": 123456,
  "prompt": "Change the background to a sunny beach while keeping the person unchanged",
  "quality": "540p"
}

组合请求示例：Mask + 参考图

{
  "video_media_id": 123456,
  "prompt": "Replace @selection0 with @img0, keep lighting consistent and natural",
  "img_ids": [987654],
  "mask_ids": ["3847593904"],
  "keyframe_id": 1,
  "quality": "540p"
}

功能示例

序号	基础功能	细分功能名称	适用场景
1	Swap	单人替换	替换视频中的 1 个主体 / 人物
2	Swap	多人替换	同时替换 2–3 个主体 / 人物
3	Add	智能添加	自动检测最佳位置，添加饰品、道具、角色等
4	Edit	物体消除（Remove）	移除指定物体，并智能补全背景；可用于去除视频中的水印、Logo 等
5	Edit	自由输入（Type Anything）	通过一段 Prompt，改变光线、季节、天气等场景效果
6	Edit	文字替换	识别并替换视频中的嵌入文字
7	Restyle	场景风格迁移	一键转换为 3D、2D、漫画、水墨等不同风格

1. 单人替换

{
  "video_media_id": 1234,
  "prompt": "@selection0 subject is swapped with @img0",
  "img_ids": [
    123
  ],
  "mask_ids": [
    "3847593904"
  ],
  "keyframe_id": 1,
  "quality": "540p"
}

2. 多人替换

{
  "video_media_id": 1234,
  "prompt": "@selection0 subject is swapped with @img0\n@selection1 subject is swapped with @img1\n@selection2 subject is swapped with @img2",
  "img_ids": [
    123,
    124,
    125
  ],
  "mask_ids": [
    "3847593904",
    "3847593905",
    "3847593906"
  ],
  "keyframe_id": 1,
  "quality": "540p"
}

3. 智能添加

{
  "video_media_id": 1234,
  "prompt": "add @img0, @img1",
  "img_ids": [
    123,
    124
  ],
  "quality": "540p"
}

图片可选，主要用于识别你希望添加的内容。

4. 物体消除（Remove）

{
  "video_media_id": 1234,
  "prompt": "remove @selection0",
  "mask_ids": [
    "3847593904"
  ],
  "keyframe_id": 1,
  "quality": "540p"
}

Mask（选区）可选，主要用于帮助识别你希望删除的内容。

5. 自由输入（Type Anything）

{
  "video_media_id": 1234,
  "prompt": "把天气变成冬天白天",
  "quality": "540p"
}

6. 文字替换

{
  "video_media_id": 1234,
  "prompt": "change the text to \"Happy Birthday\"",
  "quality": "540p"
}

7. 场景风格迁移

{
  "video_media_id": 1234,
  "prompt": "the video is restyled with @img0",
  "img_ids": [
    123
  ],
  "quality": "540p"
}

可上传参考图片，也可直接使用文字描述风格。

参数组合与占位符规则

规则	说明
视频来源	`source_video_id` 与 `video_media_id` 必须且只能填写一个。
图片占位符	`@img0` 对应 `img_ids[0]`，`@img1` 对应 `img_ids[1]`，按数组顺序从 0 开始；Prompt 引用的下标必须存在。
Mask 占位符	`@selection0` 对应 `mask_ids[0]`，`@selection1` 对应 `mask_ids[1]`；不要自行构造 `mask_id`。
Mask 对应关系	使用 `mask_ids` 时，视频来源、`keyframe_id` 和 Mask ID 必须与 Mask 接口调用保持一致。
数组数量	`img_ids` 和 `mask_ids` 当前均最多填写 3 个；只填写 Prompt 实际引用的项目。

响应字段

字段	类型	说明
`ErrCode`	integer	错误码，`0` 表示成功
`ErrMsg`	string	错误信息，成功时通常为 `Success`
`Resp.video_id`	integer	视频任务 ID，用于查询任务状态
`Resp.credits`	integer	创建响应返回的任务积分值，用于展示和对账；不应单独视为账户最终扣费凭证

响应示例

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

示例中的 credits 仅展示字段结构，不代表固定价格。

积分与计费

Modify 按源视频时长和输出分辨率计费：360p 为 8 Credits/秒，540p 为 10 Credits/秒，720p 为 12 Credits/秒。最终扣费和失败后的返还以账户用量明细、任务最终状态及「PixVerse 计费规则」为准。

下一步

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

注意事项

仅做整体编辑时可直接填写普通 prompt，无需参考图或 Mask。

使用 Mask 时，用 @selection0、@selection1 引用，并传入对应 mask_ids 和单数 keyframe_id。

使用参考图时，用 @img0、@img1 引用，并传入对应 img_ids。

Modify 更适合明确编辑目标，不建议一次提出过多互相冲突的修改。

视频编辑 Modify