# AI 发型虚拟试戴

# 概览
用最前沿的 AI 技术试遍各式发型，男女都照顾到，满足不同的性别与风格偏好。
风格的世界大门为您打开：卷发、长发、平头，还有更多。我们的 AI 发型变身让您轻松尝试，现在就找到您的理想发型！
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg)


---

## 接入指南
* API Playground

您可以用 API Playground 测试 AI 发型虚拟试戴功能，边试边熟悉试戴流程，理解会更透彻。

API Playground 地址：
[https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/](https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/)


---

* 接口流程

本指南将带您走完全流程：

AI 发型虚拟试戴接口的流程：
**接口地址：** `/s2s/v2.1/task/hair-transfer`
**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`
**流程步骤：**
1. **准备图片上传：**
  - 第一步是准备一张自拍照。
2. **列出预设模板，或使用您自己的参考照片**
**选择参考来源**
参考素材有两种方式：

| 方式 | 适用场景 | 实现提示 |
|  --- | --- | --- |
| **预设模板**（`template_id`） | 快速上手（例如"卷发波波头""侧分刘海"） | 调用 `/s2s/v2.1/task/template/hair-transfer`，挑一个 `template_id`。 |
| **自定义参考图**（`ref_file_url` / `ref_file_id`） | 用户上传自己的风格照片，或使用提供的图片链接 | 用同一个 File 接口上传；参考图若已托管在网上，用 `ref_file_url` 即可。 |

1. **发起 AI 任务并取得 Task ID：**
  - 把上传好的图片连同发型配置，通过 HTTP POST 请求送到
`/s2s/v2.0/file`
。
  - 响应会返回一个唯一的任务 ID，用于标识本次调用。
2. **轮询任务状态（持续检查）：**
  - 用取得的
`task_id`
 通过 HTTP GET 请求定期轮询任务状态（例如
`GET /task/${task_id}`
）。
  - 持续留意：
    - `Task_status = "success"`
（处理完成）。
    - `Task_status = "error"`
（视情况排查或重试）。
  - 状态转为 success 后，按流程继续往下走。

这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。


---

* 鉴权

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

```
Authorization: Bearer YOUR_API_KEY
```

API Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。


---

* 接口使用指引

本指引说明如何上传图片、准备参考图，以及创建虚拟试戴任务。


---

* 第 1 步：用 File 接口上传文件，或提供一个有效的图片 URL

用 **File 接口**（`/s2s/v2.0/file`）上传目标用户图片。
如果您已有公开可访问的图片 URL，第 1 到第 3 步可以跳过。
**图片要求：**
* 上传一张高分辨率的自拍照。
* 确保照片把整个人体完整、清楚地呈现出来。
* 避免背景里有多人，或杂乱干扰的物体。

**请求示例：**

```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": "selfie_01_3dbd1b6683.jpg",
        "file_size": 547541
      }
    ]
  }'
```


---

* 第 2 步：取得 File 接口响应

响应中包含：
* 用于创建 AI 任务的
`file_id`
。
* 用于上传实际图片文件的
`requests.url`
。

**响应示例：**

```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"
            }
          }
        ]
      }
    ]
  }
}
```


---

* 第 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 步：准备参考图
  * 4.1 取得预设图片模板

用 **模板接口**（`/s2s/v2.1/task/template/hair-transfer`）取得预设参考模板列表：

```bash
curl --request GET \
  --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```
* 4.2 上传参考图

您可以：
* 用 File 接口（
`/s2s/v2.0/file`
）上传参考图，或
* 提供一个有效的图片 URL。

**支持的图片：**
* 另一张自拍照，作为参考图。

详细规格见 **[文件规格与错误码](#section/overview/File-Specs-and-Errors)**。


---

* 第 5 步：创建 AI 发型虚拟试戴任务

用 **AI 任务接口**（`/s2s/v2.1/task/hair-transfer`）创建虚拟试戴任务。
**参数：**
* 用户图片：
`src_file_id`
 或
`src_file_url`
。
* 参考图：
`ref_file_id`
、
`ref_file_url`
 或
`template_id`
。

**请求示例：**

```bash
curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg",
    "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png"
  }'
```
**响应示例：**

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


---

* 第 6 步：轮询任务结果

用任务 ID 查看状态：

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


---

* 第 7 步：取回结果

成功的响应会给出结果图片的下载 URL：

```json
{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}
```
API 密钥无效的报错响应：

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


---

应用场景：
应用场景：
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg)
拍摄建议：
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png)
## 文件规格与错误码
* 支持的格式与尺寸

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI 发型虚拟试戴 | 长边 <= 1024，脸部宽度 >= 128，脸部姿态：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，仅支持单人脸，须呈现完整脸部 | < 10MB | jpg/jpeg |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| error_no_shoulder | 源图中看不到肩部 |
| error_large_face_angle | 上传图片中的脸部角度过大 |
| error_insufficient_landmarks | 源图中检测不到足够的脸部或人体关键点 |
| error_hair_too_short | 输入的头发太短 |
| error_face_pose | 源图的脸部姿态不受支持 |

* 运行环境与依赖

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



---

## 常见问题
**问：可以自己指定发型来试戴吗？**
**答：** 当然可以，用您自己的参考照片就能试自定义发型。AI 发型虚拟试戴支持两种方式指定想要的发型：
1. **上传您自己的参考图**
通过 File 接口（`/s2s/v2.0/file`）上传一张高分辨率的自拍照或风格照（例如展示目标发型的人物照）。上传完成后，创建 AI 任务时用返回的 `file_id` 或公开 URL 作为参考来源。
2. **提供有效的图片 URL**
若参考图已托管在网上（例如您自己的服务器或 CDN），可直接在请求体的 `ref_file_url` 字段填入其 HTTPS URL。

通过 `/s2s/v2.1/task/hair-transfer` 提交任务时，二选一填入：
- `src_file_id`
（您的自拍照）与
`ref_file_id`
（您的自定义参考图），

或
- `src_file_url`
 与
`ref_file_url`
。

请确保两张图片都符合要求：
- 支持格式：仅限 JPG/JPEG
- 文件大小 10 MB 以内
- 长边 ≤ 1024 像素
- 脸部宽度 ≥ 128 像素
- 头部姿态在允许范围内（俯仰角：−10° 到 +10°，偏航角：−45° 到 +45°，翻滚角：−15° 到 +15°）
- 画面中只有单人脸，正脸视角，头发清楚可见

有了这份灵活度，只要照片里有参考，几乎任何发型都能套用，不限于预设模板。


---

## 点数消耗
| AI 功能 | 消耗点数 |
|  --- | --- |
| AI 发型虚拟试戴 V2.0 | 预设模式 1 点  自定义模式 2 点 |
| AI 发型虚拟试戴 V2.1 | 预设模式 2 点  自定义模式 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_hairstyle.yaml)

## V2.1

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

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

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