概览

SWAP 是一项强大的视频编辑能力。你可以上传或生成一段视频，然后选择其中的一帧，并选中想要编辑的对象。接着，上传一张目标图片，系统将为你生成一个全新的视频。

通过此功能，你可以创作出各种有趣且富有创意的视频，例如人物替换、跳舞特效、影视翻拍、视觉再创作等。

在使用该功能时，请配合 mask/selection API 一起使用，以指定需要替换的目标区域。目前暂不支持外部 mask_url 输入。

前提条件

开始之前，请确保您拥有：

有效的拍我AI API 密钥

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

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

用于多帧的图像，并获得对应的img_id

以下任一：

从拍我AI 生成的 video_id
或者

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

最大分辨率：1920

最大文件大小：50MB

最大时长：30秒

快速调用

1: 准备视频

2. 生成Mask API

3. 视频替换API 任务

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

使用步骤

步骤 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 字段中。

目标对象图片

Step 2: 生成Mask 请求

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

Request

Responses

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

🔧 参数

参数名	是否必须	属性	描述
source_video_id	source_video_id 或 video_media_id, 二选一	int	video_id 拍我AI API
video_media_id	source_video_id 或 video_media_id, 二选一	int	上传的外部视频
keyframe_id	否	int	从1 到最后视频帧. 如果不提供默认为1

Step 3: Send Swap API Request

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

使用mask_id时, 相关的video_id , keyframe_id 需要跟在生成Mask API 时的参数匹配

Request

🔧 参数

参数名	是否必须	属性	描述
source_video_id	source_video_id 或 video_media_id, 二选一	int	video_id 拍我AI API
video_media_id	source_video_id 或 video_media_id, 二选一	int	上传的外部视频
keyframe_id	是	int	从1 到最后视频帧. 如果不提供默认为1
mask_id	是	string	Mask selection API 结果里面的 mask_id
img_id	是	int	img_id from upload API
quality	是	string	"360p","540p","720p". 不支持"1080p"
original_sound_switch	否	int	是否保留视频原声

步骤 4. 处理API响应

API返回包含 video_id 的JSON响应：

{
  "ErrCode": 0,
  "ErrMsg": "success",
  "Resp": {
    "video_id": 0
  }
}

步骤 5 检查生成状态

创建任务后，您将收到一个 video_id

使用此 video_id 定期查询获取视频生成状态API

处理完成时，状态将从 5 变为 1

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 5,
   "style": "string",
   "url": "string"
 }
}

步骤 6 下载生成的视频

您可以通过"url"访问生成的视频

  {
 "ErrCode": 0,
 "ErrMsg": "string",
 "Resp": {
   "create_time": "string",
   "id": 0,
   "modify_time": "string",
   "negative_prompt": "string",
   "outputHeight": 0,
   "outputWidth": 0,
   "prompt": "string",
   "resolution_ratio": 0,
   "seed": 0,
   "size": 0,
   "status": 1,
   "style": "string",
   "url": "string"
 }
}

故障排除

常见问题

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

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

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

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

常见错误代码

400/500 状态：代码错误

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

400017：无效参数

500044：达到并发生成限制

视频编辑(Swap)使用指南

概览#

前提条件#

快速调用#

使用步骤#

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

外部视频#

PixVerseAPI 生成的视频#

目标对象图片#

Step 2: 生成Mask 请求#

Step 3: Send Swap API Request#

步骤 4. 处理API响应#

步骤 5 检查生成状态#

步骤 6 下载生成的视频#

故障排除#

常见问题#

常见错误代码#

概览