# AI 照片背景更换

# 概览
AI 图片换背景接口会先把主体从原背景中分离出来，再对图片做增强，可广泛用于电商商品图等商用场景。
这个接口支持用自定义提示词或预设模板来替换背景。
**使用示例**
调整前：
![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg)
调整后：
![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg)
调整前：
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg)
调整后：
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg)


---

## 接入指南
**1. 上传图片**
通过以下接口取得上传 URL 与文件 ID：

```
POST /s2s/v2.0/file
```
用返回的 URL 把图片上传上去。
也可以提供您自有存储上可公开访问的图片 URL。
**2. 准备背景描述提示词，或挑选背景模板。**

```
GET /s2s/v2.0/task/template/bg-replace
```
取得预设背景模板列表，用其中的 template_id 选定一个。使用 prompt（默认方式）时，背景依据您给的提示词生成；使用 template 时，背景由 template_id 指定的预设模板生成，prompt 参数将被忽略。
**3. 执行分析任务**

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

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


---

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

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI 图片换背景 | 长边不超过 4096 像素。 | < 10MB | jpg/jpeg/png |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| exceed_max_filesize | 输入文件大小超出上限 |
| size_mismatch_on_input_image_and_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 图片换背景 V2.0 | 4 |



---

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_photo_background_change.yaml)

## V2.0

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