檔案規格與錯誤

AI 模糊背景

概述

淺景深（bokeh）效果是一種受歡迎的攝影技術，用於模糊照片背景並讓主體對焦。它為照片增添藝術氣息，使其看起來更專業且吸睛。

用 AI 模糊背景 API 創造專業外觀的照片，它自動隔離主體並套用自然的背景模糊，將注意力引導到最重要的地方。

使用情境範例：

人像增強套用自然的淺景深效果，讓主體突出，並提升個人頭像或人像照片的視覺品質。
之前：
之後：
專業形象照從一般照片創造類攝影棚的背景模糊效果，用於商務個人檔案與企業目錄。
之前：
之後：

整合指南

輸入需求與處理標準：

上傳包含清晰、顯著前景主體的圖片。
圖片最長邊不得超過 4,096 px。
來源檔案大小必須低於 10 MB。
至少需要一位清晰可見的前景主體。
僅支援單主體分析。若出現多人，API 會自動選擇可見面積最大的主體。

工作流程：

呼叫 File API。
從回應中取得簽名的上傳網址。
將實際圖片上傳到回傳的網址。
建立 AI 任務。
設定 Webhook 或輪詢任務狀態直到完成。
處理成功後下載生成的結果圖片。

步驟 1 — 使用 File API 上傳檔案 metadata

使用 POST /s2s/v2.0/file 建立檔案記錄，並取得來源圖片的上傳細節。

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 回應範例：

{
  "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 上傳來源圖片。

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

請求範例：

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 回應：

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

步驟 5 — 設定ebhook 或輪詢任務結果

設定與驗證細節請參考 webhook 整合指南。

輪詢時，使用回傳的 task_id 查詢任務狀態。

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 中包含下載網址。

{
  "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 回應。

{
  "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

下载 OpenAPI 描述

ai_photo_background_blur.json

ai_photo_background_blur.yaml

概述

电子邮件

YouCamOnlineEditor_API@perfectcorp.com

许可证

服务条款

语言

服务器

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