# AI 照片背景虚化

# 概览
背景虚化（焦外）是摄影里很常用的一种手法：把背景虚下去，让主体更突出。照片加一点这种效果更有艺术味，看着更专业、更抓人眼球。
用 AI 图片背景虚化接口就能做出专业观感的照片：它自动把主体分离出来，套上自然的背景虚化，把视线引到最该看的地方。
**使用场景示例：**
* 人像美化
套上自然的焦外虚化，让人物更突出，头像照、人像照的画质观感更好。
调整前：
![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg)
调整后：
![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg)
* 专业形象照
用普通照片做出照相馆级的背景虚化效果，适合商务头像、企业员工名录。
调整前：
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg)
调整后：
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg)



---

## 接入指南
**输入要求与处理条件：**
- 上传一张前景主体清楚、突出的图片。
- 图片长边不得超过
**4,096 px**
。
- 源文件大小须小于
**10 MB**
。
- 至少需要一个清晰可见的前景主体。
- 只支持单人分析。画面中有多人时，接口会自动选取可见面积最大的那位主体。

**流程：**
1. 调用 File 接口。
2. 从响应中取得签名的上传 URL。
3. 把实际图片上传到该 URL。
4. 创建 AI 任务。
5. 配置 Webhook，或轮询任务状态直到完成。
6. 处理成功后下载生成的结果图片。



---

**第 1 步 — 用 File 接口上传文件元数据**
用 `POST /s2s/v2.0/file` 建立文件记录，取得源图的上传信息。

```bash
curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "full_body_photo_01_3dbd1b6683.jpg",
        "file_size": 547541
      }
    ]
  }'
```
**File 接口响应示例：**

```json
{
  "status": 200,
  "data": {
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "full_body_photo_01_3dbd1b6683.jpg",
        "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud",
        "requests": [
          {
            "method": "PUT",
            "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...",
            "headers": {
              "Content-Length": "547541",
              "Content-Type": "image/jpg"
            }
          }
        ]
      }
    ]
  }
}
```


---

**第 2 步 — 取得 File 接口响应内容**
响应包含：
| 字段 | 说明 |
|  --- | --- |
| `file_id` | 用于创建 AI 任务的标识。 |
| `requests.url` | 上传实际图片文件的签名 URL。 |
| `requests.method` | 上传方式，通常为 `PUT`。 |
| `requests.headers` | 上传请求所需的请求头。 |



---

**第 3 步 — 把图片上传到提供的 URL**
用 File 接口响应中的 `requests.url` 上传源图。

```bash
curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \
  --header 'Content-Type: image/jpg' \
  --header 'Content-Length: 547541' \
  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'
```


---

**第 4 步 — 创建 AI 任务**
用 `POST /s2s/v2.0/task/bg-blur` 创建 AI 任务。
| 参数 | 说明 | 示例 |
|  --- | --- | --- |
| `src_file_id` | File 接口上传流程返回的文件 ID。走上传文件流程时必填。 | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` |
| `src_file_url` | 源图的直接 URL。可作为 `src_file_id` 的替代方案。 | `"https://example.com/selfie.jpg"` |
| `intensity` | 模糊强度。0 表示不模糊，100 表示最大模糊。 | 50 |

**请求示例：**

```javascript
const resp = await fetch(
  'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer <YOUR_TOKEN_HERE>'
    },
    body: JSON.stringify({
      src_file_url: 'https://example.com/selfie.jpg',
      intensity: 50
    })
  }
);

const data = await resp.json();
console.log(data);
```
**AI 任务接口响应：**

```json
{
  "status": 200,
  "data": {
    "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT"
  }
}
```


---

**第 5 步 — 配置 Webhook 或轮询任务结果**
配置与验证细节见 [Webhook 接入指南](/develop/webhook)。
若走轮询，请用返回的 `task_id` 查看任务状态。

```bash
curl --request GET \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/<YOUR_TASK_ID> \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json'
```


---

**第 6 步 — 取回结果图片**
处理成功时，响应会在 `data.results.url` 中给出下载 URL。

```json
{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}
```
**API 密钥无效的响应：**
访问令牌无效时，接口返回 `401` 响应。

```json
{
  "status": 401,
  "error": "Unauthorized",
  "error_code": "InvalidAccessToken"
}
```


---

## 文件规格与错误码
**文件规格：**
| 规格项 | 要求 |
|  --- | --- |
| 图片类型 | 图片需包含一位清楚、突出的前景主体或人物。 |
| 长边分辨率上限 | 长边不得超过 **4096 px**。 |
| 文件大小上限 | 须小于 **10 MB**。 |
| 支持格式 | `jpg`、`png`。 |

**错误码：**
| 错误码 | 说明 |
|  --- | --- |
| `exceed_max_filesize` | 源图超出允许的尺寸或文件大小上限。长边不得超过 4096 px，文件大小须保持在 10 MB 以下。 |
| `error_nsfw_content_detected` | 在源图或生成的结果图中检测到疑似不适宜内容（NSFW）。 |
| `invalid_parameter` | 源键、目标键、动作、模式取值、强度档位或任务配置中提供了无效参数。 |
| `error_download_image` | 源图片下载失败。 |
| `error_decode_image` | 源图片解码失败。 |

**运行环境与依赖：**
| 工具 / 语言 | 建议运行时版本 |
|  --- | --- |
| cURL | Bash ≥ 3.2；curl ≥ 7.58（支持现代 TLS/HTTP）；jq ≥ 1.6（稳健的 JSON 解析）。 |
| Node.js | Node ≥ 18，以支持全局 `fetch`。 |
| JavaScript 浏览器支持 | Chrome / Edge ≥ 80、Firefox ≥ 74、Safari ≥ 13.1。 |
| PHP | PHP ≥ 7.4（兼容现代 TLS）；建议 ext-curl，或 `allow_url_fopen=On` 并具备 OpenSSL 与 JSON 支持。 |
| Python | Python ≥ 3.10（支持 f-string）；requests ≥ 2.20.0。 |
| Java | Java 11+（HttpClient）；Jackson Databind ≥ 2.12.0。 |



---

## 点数消耗
| AI 功能 | 消耗点数 |
|  --- | --- |
| AI 图片背景虚化 V2.0 | 1 |



---

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

## V2.0

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