视频编辑(Modify) 功能使用指南

概述

视频编辑(Modify) 功能支持对已有视频的任意部分进行编辑，包括添加、替换、删除、修改元素，或改变整体风格。

它能够帮助你快速完成视频二创，让一个视频衍生出更多全新的创意可能。

核心能力

替换(Swap)：替换视频中的人物或主体

添加(Add)：向视频中添加新元素（例如饰品、道具、角色）

编辑(Edit)：通过自由 Prompt 修改视频内容

重绘(Restyle)：将整个视频转换为不同的视觉风格

前期条件

开始之前，请确保您拥有

有效的拍我AI API 密钥

每个API请求的唯一 Ai-trace-id

已开通并激活订阅计划，且账户中有足够可用额度；

用于视频编辑的图像，并获得对应的img_id

以下任一：

从拍我AI 生成的 video_id

或者

支持格式的上传视频（mp4、mov）

最大分辨率：1920

最大文件大小：100MB

最大时长：30秒

来自 swap_mask 接口的 mask_id，或你自己提供的 mask_url

当使用 Swap 功能时，需要提供 keyframe_id

要求与校验规则

当使用特定功能时，如果 Prompt 中使用了 mask，需要使用 @selection0 的形式引用。多个 mask 时，依次使用 @selection1、@selection2。如果上传了参考图片，则使用 @img0、@img1 等。

请确保 Prompt 中引用的 mask 与图片数量，与实际传入的数量一致。如果数量不一致，或 Prompt 中未明确引用，则最终效果可能与预期不符。

如果你暂时没有 mask 数据，可以使用 Swap Mask API。此时，用于生成 mask 的 video_id 必须与生成请求中使用的 mask_id 对应。

如果你已经有自己的 mask 图片，可以通过 mask_url 参数传入。

keyframe_id 用于指定以视频的哪一帧作为编辑帧。因此，在创建 mask 时使用的帧，必须与请求中的 keyframe_id 保持一致。

1: 准备视频/图片/Mask

2. 生成 Mimic API

3. 查询任务状态, 下载视频

使用步骤

步骤 1: 准备视频 & 图片 & Mask

1-1 视频

外部视频

请求Curl

返回结果

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

PixVerseAPI 生成的视频

如果您之前使用我们的API生成了视频，您应该已经有一个 video_id。
要扩展此视频，请将 video_id 传递到生成请求的 source_video_id 字段中。

1-2 图片

Mask

1-3-1 通过mask/selection(主体替换Mask) API 生成 Mask ID

Request

Responses

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

1-3-2 如果是自己的mask , 请用mask_url

Step 2: 视频编辑(Modify) 功能请求

如果用拍我API上传了视频请使用 "source_video_id":111 , "video_media_id" 作为

R
Request

Responses

{
  "ErrCode": 0,
  "ErrMsg": "string",
  "Resp": {
    "video_id": 0,
    "credit":10
  }
}

🔧 参数

参数名	类型	必填	描述	示例 / 可选值	备注
`source_video_id`	int	`source_video_id` 或 `video_media_id` 二选一必填	PixVerse 生成的视频	`12345`	不可与 `video_media_id` 同时使用
`video_media_id`	int	`source_video_id` 或 `video_media_id` 二选一必填	外部上传的视频	`12345`	不可与 `source_video_id` 同时使用
`prompt`	string	是	描述你希望对视频进行的修改		如果 Prompt 中使用了 mask，请使用 `@selection0`、`@selection1`；如果使用参考图片，请使用 `@img0`、`@img1`
`img_ids`	array[int]	否	Prompt 中使用的图片 ID	`[123,456]`	如果传入，至少需要 1 个
`mask_ids`	array[string]	可选，与 `mask_urls` 二选一	通过 Mask API 获得的 mask ID	`["3847593904"]`	如果传入，至少需要 1 个
`mask_urls`	array[string]	可选，与 `mask_ids` 二选一	公网可访问的 mask 图片地址	`["https://example.com/mask.png"]`	如果传入，至少需要 1 个
`keyframe_id`	int	否	指定使用视频中的哪一帧进行编辑	`1`	只能传一个值，无需与 `mask_ids` 数量一致
`quality`	string	是	输出视频分辨率	`"360p"`、`"540p"`、`"720p"`	不支持 `1080p`
`seed`	int	否	用于复现结果的随机种子	`0 ~ 2147483647`	可选

功能示例


{\n  "video_media_id": 1234,\n  "prompt": "@selection0 subject is swapped with @img0",\n  "img_ids": [123],\n  "mask_ids": ["3847593904"],\n  "keyframe_id": 1,\n  "quality": "540p"\n}
{\n  "video_media_id": 1234,\n  "prompt": "@selection0 subject is swapped with @img0\n@selection1 subject is swapped with @img1\n@selection2 subject is swapped with @img2",\n  "img_ids": [123, 124, 125],\n  "mask_ids": ["3847593904", "3847593905", "3847593906"],\n  "keyframe_id": 1,\n  "quality": "540p"\n}
{\n  "video_media_id": 1234,\n  "prompt": "add @img0, @img1",\n  "img_ids": [123, 124],\n  "quality": "540p"\n}
{\n  "video_media_id": 1234,\n  "prompt": "remove xxx",\n  "mask_ids": ["3847593904"],\n  "quality": "540p"\n}
{\n  "video_media_id": 1234,\n  "prompt": "把天气变成冬天白天",\n  "quality": "540p"\n}
{\n  "video_media_id": 1234,\n  "prompt": "change the text to \"Happy Birthday\"",\n  "quality": "540p"\n}
{\n  "video_media_id": 1234,\n  "prompt": "the video is restyled with @img0",\n  "img_ids": [123],\n  "quality": "540p"\n}

序号	基础功能	细分功能名称	适用场景	调用方法
1	Swap	单人替换	替换视频中的 1 个主体 / 人物	`{\n "video_media_id": 1234,\n "prompt": "@selection0 subject is swapped with @img0",\n "img_ids": [123],\n "mask_ids": ["3847593904"],\n "keyframe_id": 1,\n "quality": "540p"\n}`
2	Swap	多人替换	同时替换 2–3 个主体 / 人物	`{\n "video_media_id": 1234,\n "prompt": "@selection0 subject is swapped with @img0\n@selection1 subject is swapped with @img1\n@selection2 subject is swapped with @img2",\n "img_ids": [123, 124, 125],\n "mask_ids": ["3847593904", "3847593905", "3847593906"],\n "keyframe_id": 1,\n "quality": "540p"\n}`
3	Add	智能添加	自动检测最佳位置，添加饰品、道具、角色等	`{\n "video_media_id": 1234,\n "prompt": "add @img0, @img1",\n "img_ids": [123, 124],\n "quality": "540p"\n}` 图片可选，主要用于识别你希望添加的内容。
4	Edit	物体消除（Remove）	移除指定物体，并智能补全背景；可用于去除视频中的水印、Logo 等	`{\n "video_media_id": 1234,\n "prompt": "remove xxx",\n "mask_ids": ["3847593904"],\n "quality": "540p"\n}` Mask（选区）可选，主要用于帮助识别你希望删除的内容。
5	Edit	自由输入（Type Anything）	通过一段 Prompt，改变光线、季节、天气等场景效果	`{\n "video_media_id": 1234,\n "prompt": "把天气变成冬天白天",\n "quality": "540p"\n}`
6	Edit	文字替换	识别并替换视频中的嵌入文字	`{\n "video_media_id": 1234,\n "prompt": "change the text to \"Happy Birthday\"",\n "quality": "540p"\n}`
7	Restyle	场景风格迁移	一键转换为 3D、2D、漫画、水墨等不同风格	`{\n "video_media_id": 1234,\n "prompt": "the video is restyled with @img0",\n "img_ids": [123],\n "quality": "540p"\n}` 可上传参考图片，也可直接使用文字描述风格。

故障排除

常见问题

您的视频卡在"生成中"状态，长时间等待后仍未完成。

请检查您是否为每个请求使用相同的 AI-trace-ID。这是导致此问题的最常见原因。

状态代码：1：生成成功；5：等待生成；7：内容审核失败；8：生成失败；

如果遇到状态代码 7，意味着您生成的视频被我们的内容审核系统过滤。请修改参数后重试。用于被过滤视频的积分将自动退还到您的账户。

常见错误代码

400/500 状态：代码错误

400013：无效的绑定请求：参数类型或值不正确

400017：无效参数

500044：达到并发生成限制

计费

模型	计费方式	360p	540p	720p	1080p
-	按s 收费	8	10	12	-

视频编辑(Modify) 功能使用指南

概述#

核心能力#

前期条件#

要求与校验规则#

使用步骤#

步骤 1: 准备视频 & 图片 & Mask#

1-1 视频#

外部视频#

PixVerseAPI 生成的视频#

1-2 图片#

Mask#

1-3-1 通过mask/selection(主体替换Mask) API 生成 Mask ID#

1-3-2 如果是自己的mask , 请用mask_url#

Step 2: 视频编辑(Modify) 功能请求#

故障排除#

常见问题#

常见错误代码#

计费#

概述