# AI 耳环虚拟试戴

# 概览
AI 耳环虚拟试戴，行业顶级方案
领先的 AI 虚拟穿耳与耳环试戴模拟方案
用一张 2D 图片就能做出真实灵动的 AI 耳环虚拟试戴，不必花钱做 3D 建模。我们的先进算法能生成栩栩如生的试戴效果，光影细腻、动态符合物理规律。
## 接入指南
本指南将带您走完全流程：
* **接口地址：**

`/s2s/v2.0/task/2d-vto/earring`
* **鉴权：**
 所有请求都需要
`Authorization: Bearer YOUR_API_KEY`
* **流程：**
  1. **准备自拍图片：**
 上传一张图片，或提供有效的图片 URL
  2. **准备耳环图片：**
 上传一张耳环商品图片，或提供有效的商品图片 URL
  3. **发起 AI 任务并获取 Task ID：**
 从响应中取到
`task_id`
。
  4. **轮询状态（`GET`）：**
 用
`task_id`
 查询任务状态，持续轮询直到
`task_status`
 为
`"success"`
 或
`"error"`
。



---

* API Playground

用官方在线调试台交互式地体验与测试接口：
**API Playground：**
[http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/)


---

* 鉴权

- 请在请求头中以
**Bearer Token**
 方式带上您的 API 密钥：

```
Authorization: Bearer YOUR_API_KEY
```

API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。
*   1. 上传图片

您可以把文件直接上传到服务器，也可以在 VTO 任务参数中提供有效的图片 URL。
* 上传接口


```
POST /s2s/v2.0/file
```
如果您已有公开可访问的图片 URL，这一步可以跳过。
您可以把文件上传到 File 接口响应中给出的 URL，之后调用 AI 任务时使用 File 接口返回的 `src_file_id`；也可以在 VTO 任务参数中以 `src_file_url` 提供有效的图片 URL。`src_file_id` 或 `src_file_url` 就是虚拟试戴的目标图。
您还需用 `ref_file_ids` 或 `ref_file_urls` 提供一张耳环商品图作为参考，套用到您的 `src_file_id` 或 `src_file_url` 上。
AI 引擎支持自动去除耳环商品图的背景。您也可以为手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或耳环商品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮挡蒙版图，用于微调分割效果。


---

*   1. 创建 AI 耳环虚拟试戴任务并轮询结果

图片和模板 ID 备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。
* 创建任务接口


```
POST /s2s/v2.0/task/2d-vto/earring
```
* 轮询接口


```
GET /s2s/v2.0/task/2d-vto/earring/{task_id}
```


---

## 文件规格与错误码
* AI 耳环虚拟试戴规格

**支持的耳环参考图**
* 单只耳环的正面图，画面清楚、无遮挡。
* 所有参数（包括锚点、蒙版、位置等）
**仅**
在参考图为
**单只耳环**
佩戴状态时生效。
* 若试戴参考图中是
**两只耳环**
，全部参数都将采用
**自动检测与默认设置**
。
* **双耳**
同时试戴时，以较清晰的那只耳朵为源，另一侧由镜像生成。

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg)
**支持的自拍图视角**
* AI 耳环虚拟试戴支持正脸图片，但侧脸图片的效果最好。

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png)
**earring_wearing_location: 长度为 2 的整数数组**
指定在自拍图中要佩戴耳环的位置。
默认值：null（使用引擎默认值）
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg)
**earring_scale: 大于 0 的数值**
按厘米控制耳环大小。
默认值：null（使用引擎默认值）
**earring_is_right_ear: boolean**
表示耳环是否戴在右耳，默认戴在右耳。
默认值：true
**earring_occluded_type: number（枚举：0、1、2）**
指定遮挡类型：
0 为自动检测
1 为有遮挡
2 为无遮挡
默认值：0
**earring_shadow_intensity: float（0.0 到 1.0）**
控制阴影强度：
0.0 表示无阴影
1.0 表示最大阴影
默认值：0.15
**earring_ambient_light_intensity: float（0.0 到 1.0）**
定义光线在多大程度上参考自拍图：
0.0 忽略自拍图的光线
1.0 完全匹配自拍图的光线与阴影渲染
默认值：1.0
**earring_anchor_point: 像素坐标下 1 个点组成的数组（可选）**
指定在耳环商品图中的佩戴位置。
默认值：null（使用引擎默认值）
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg)


---

* 支持的格式与尺寸

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI 耳环虚拟试戴 | 长边 <= 4096 | < 10MB | jpg/jpeg/png |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| RUNTIME_ERROR | 运行时发生未知错误 |
| PHOTO_DETECTION_FAIL | 用户照片无法正确处理，例如未检测到手 |
| OBJECT_DETECTION_FAIL | 商品照片无法正确处理，例如未检测到商品 |
| PHOTO_CHECK_INVALID | 用户照片的姿态或尺寸不符合要求 |
| INPUT_ERROR | 输入文件格式有误 |
| INPUT_MAIN_IMAGE_EMPTY | 必须提供用户图片 |

* 运行环境与依赖

| 示例代码语言 / 工具 | 建议运行时版本 |
|  --- | --- |
| 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 |



---

## JS Camera Kit


---

## 点数消耗
| AI 功能 | 消耗点数 |
|  --- | --- |
| AI 耳环虚拟试戴 V1.0 | 单件佩戴 1 点数  叠戴 2 点数 |



---

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

## V1.0

 - [POST /s2s/v2.0/task/2d-vto/earring](https://docs.perfectcorp.com/zh-cn/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post.md): 本接口用于发起 AI 耳环虚拟试戴流程。您需要提供源文件与参考图（URL 或文件 ID），以及用于对齐、阴影与佩戴位置的具体参数。任务会异步处理，您可以使用本响应返回的 task_id 查询其状态。
 - [GET /s2s/v2.0/task/2d-vto/earring/{task_id}](https://docs.perfectcorp.com/zh-cn/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1%7Btask_id%7D/get.md)