# AI 视频背景替换

# 概览
**AI 视频背景替换**
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Green_Screen_ddb7892393.png)
AI 视频背景替换接口可以让您把任意背景无缝加进画面。风景、自定义图片、趣味画面随您选，创作空间完全交给您，把视频场景做到最理想的状态。
不用摄影棚，也不用绿幕。换掉视频背景轻轻松松，画面干净又专业。无论想换个新环境，还是去掉画面里多余的东西，这套方案都很合适，不必购置昂贵设备，就能做出好看的视频与教学片。


---

## 接入指南
**1. 准备源视频与背景图片**
输出为 MP4 格式，分辨率与输入一致；帧率上限为每秒 30 帧，输入超出时自动转换；时长上限 600 秒，输入视频更长时只保留前 600 秒。
背景图片须为 JPG 或 PNG 格式，分辨率最高 4096 × 4096 像素，长边不超过 4096 像素，文件大小上限 10 MB。
**2. 上传文件**
通过以下接口取得上传 URL 与文件 ID：

```
POST /s2s/v2.0/file
```
**3. 执行 AI 任务**

```
POST /s2s/v2.0/task/bg-replace-vid
```
用文件 ID 或图片 URL 作为输入提交任务。响应会返回一个 task_id，用于追踪并取回结果。
**4. 取回任务结果**

```
GET /s2s/v2.0/task/bg-replace-vid/{task_id}
```
用任务 ID 追踪状态并取得结果。
可配置 [Webhooks](/develop/webhook)，在任务完成（状态为 success 或 error）时接收异步通知。也支持轮询：反复调用任务接口，直到状态从 running 变为 success 或 error。
只有任务成功完成才计费。


---

## 文件规格与错误码
* 支持的格式与尺寸

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI 视频背景替换 | 输出为 MP4 格式，分辨率与输入一致；帧率上限为每秒 30 帧，输入超出时自动转换；时长上限 600 秒，输入视频更长时只保留前 600 秒。 背景图片须为 JPG 或 PNG 格式，分辨率最高 4096 × 4096 像素，长边不超过 4096 像素，文件大小上限 10 MB。 | 视频时长上限：600 秒  背景图片：<10MB | 封装格式：mp4 视频编码：MPEG-4、MPEG-4 AVC，音频编码：aac、amr、mp3 |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| error_download_video | 下载源视频出错 |
| error_decode_video | 解码源视频出错 |
| error_unsupported_video | 视频格式不受支持 |
| exceed_max_filesize | 输入文件大小超出上限 |
| error_nsfw_content_detected | 在源文件中检测到不适宜内容（NSFW） |
| error_decode_mask | 解码蒙版图片出错 |
| invalid_parameter | 参数取值无效 |

* 运行环境与依赖

| 示例代码语言 / 工具 | 建议运行时版本 |
|  --- | --- |
| cURL | - bash >= 3.2   - curl >= 7.58 (modern TLS/HTTP support)   - jq >= 1.6 (robust JSON parsing) |
| Node.js (JavaScript) | Node >= 18 (for global fetch) |
| JavaScript | - Chrome / Edge >= 80   - Firefox >= 74   - Safari >= 13.1 |
| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |
| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |
| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |



---

## 点数消耗
| AI 功能 | 消耗点数 |
|  --- | --- |
| AI 视频背景替换 V1.0 | 2（每秒）* |

> *若图片数量或视频时长不能整除，点数按向上取整计算。



---

License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。

Type: http
Scheme: bearer

## Download OpenAPI description

 - [AI 视频背景替换](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_video_background_replace.yaml)

## V1.0

 - [POST /s2s/v2.0/task/bg-replace-vid](https://docs.perfectcorp.com/zh-cn/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid/post.md): AI 任务是异步处理的。功能支持 Webhook 时，优先用 Webhook 来接收完成通知。配置好您的 Webhook 端点、校验 Webhook 签名，收到 `success` 或 `error` 通知后，用收到的 `task_id` 查询任务结果。配置与校验的细节请见 [Webhook 接入指南](/develop/webhook)。 若功能不支持 Webhook，或您的接入方式用不了 We
 - [GET /s2s/v2.0/task/bg-replace-vid/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_video_background_replace/v1.0/paths/~1s2s~1v2.0~1task~1bg-replace-vid~1%7Btask_id%7D/get.md)