文件规格与错误码

AI 照片背景虚化

概览

背景虚化（焦外）是摄影里很常用的一种手法：把背景虚下去，让主体更突出。照片加一点这种效果更有艺术味，看着更专业、更抓人眼球。

用 AI 图片背景虚化接口就能做出专业观感的照片：它自动把主体分离出来，套上自然的背景虚化，把视线引到最该看的地方。

使用场景示例：

人像美化套上自然的焦外虚化，让人物更突出，头像照、人像照的画质观感更好。
调整前：
调整后：
专业形象照用普通照片做出照相馆级的背景虚化效果，适合商务头像、企业员工名录。
调整前：
调整后：

接入指南

输入要求与处理条件：

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

流程：

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

第 1 步 — 用 File 接口上传文件元数据

用 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 接口响应示例：

{
  "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 上传源图。

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

请求示例：

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 任务接口响应：

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

第 5 步 — 配置 Webhook 或轮询任务结果

配置与验证细节见 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 中给出下载 URL。

{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}

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-string）；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