# AI 模糊背景

# 概述
淺景深（bokeh）效果是一種受歡迎的攝影技術，用於模糊照片背景並讓主體對焦。它為照片增添藝術氣息，使其看起來更專業且吸睛。
用 AI 模糊背景 API 創造專業外觀的照片，它自動隔離主體並套用自然的背景模糊，將注意力引導到最重要的地方。
**使用情境範例：**
* 人像增強
套用自然的淺景深效果，讓主體突出，並提升個人頭像或人像照片的視覺品質。
之前：
![](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**
。
- 至少需要一位清晰可見的前景主體。
- 僅支援單主體分析。若出現多人，API 會自動選擇可見面積最大的主體。

**工作流程：**
1. 呼叫 File API。
2. 從回應中取得簽名的上傳網址。
3. 將實際圖片上傳到回傳的網址。
4. 建立 AI 任務。
5. 設定 Webhook 或輪詢任務狀態直到完成。
6. 處理成功後下載生成的結果圖片。



---

**步驟 1 — 使用 File API 上傳檔案 metadata**
使用 `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 API 回應範例：**

```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 API 回應細節**
回應包含：
| 欄位 | 說明 |
|  --- | --- |
| `file_id` | 用於建立 AI 任務的識別碼。 |
| `requests.url` | 用於上傳實際圖片檔案的簽名網址。 |
| `requests.method` | 上傳方法，通常為 `PUT`。 |
| `requests.headers` | 上傳請求所需的標頭。 |



---

**步驟 3 — 上傳圖片到提供的網址**
使用 File API 回應中的 `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 API 上傳流程回傳的檔案 ID。使用上傳檔案工作流程時為必要。 | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` |
| `src_file_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 任務 API 回應：**

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


---

**步驟 5 — 設定ebhook 或輪詢任務結果**
設定與驗證細節請參考 [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` 中包含下載網址。

```json
{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}
```
**API Key 無效的回應：**
若 access token 無效，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-strings）；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 authentication'。請在標頭中放入您的 'API Key'：`Authorization:Bearer YOUR_API_KEY`。請注意 'Bearer' 與 'YOUR_API_KEY' 之間有一個空格。

Type: http
Scheme: bearer

## Download OpenAPI description

 - [AI 模糊背景](https://docs.perfectcorp.com/_bundle/@l10n/zh-TW/reference/ai_photo_background_blur.yaml)

## V2.0

 - [POST /s2s/v2.0/task/bg-blur](https://docs.perfectcorp.com/zh-tw/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 或無法使用
 - [GET /s2s/v2.0/task/bg-blur/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1%7Btask_id%7D/get.md)