# AI 胡型生成器

# 概览
AI 男士胡须造型模拟
AI 算法也照顾到男士：凭借精细的胡须模拟技术，络腮胡、短须、全须、圈须、八字胡、山羊胡等各式胡型都能自由虚拟试戴。
消费者还能直接看到剃前剃后的对比，不用真拿剃刀往皮肤上招呼。
胡须滤镜包含八字胡、短方胡、鸭尾胡、圈胡等十余种。
## 接入指南
1. **上传自拍**

源图有两种提供方式：

- **使用已有的公开图片 URL**
不必上传，发起 AI 任务时直接给一个可公开访问的图片 URL 即可。
- **通过 File 接口上传**
接口地址：

```
POST /s2s/v2.0/file
```
这会返回一个 `file_id`，供后续执行任务时使用。
  - ***重要***：只调用 File 接口并不等于上传了文件。您必须**手动把文件上传到 File 接口响应中给出的那个 URL**，那个 URL 就是您的上传目标，务必确认文件已成功传过去，再继续往下做。
调用 AI 接口之前，请确认文件已上传成功。先用 File 接口取到一个上传 URL，把文件上传到该位置。上传完成后，您会在响应中收到一个 ***file_id***，调用与该文件相关的 AI 功能时就用它。
> **警告：** 请注意，若未把文件上传到 File 接口响应中给出的 URL，调用 AI 接口时会得到 500 Server Error / unknown_internal_error 或 404 Not Found 错误。

1. **获取预设风格列表**
  * 调用 /s2s/v2.0/task/template/beard-style 取得预设模板列表，挑一个
`template_id`
 用于执行 AI 任务。
2. **执行 AI 任务并取得 Task ID**
用 /s2s/v2.0/task/beard-style 执行 AI 任务。目标用户图请提供 `src_file_url` 或 `src_file_id`，再给出要套用的风格 `template_id`，即可取得 `task_id`。
3. **轮询任务状态，直到成功或失败**
用 `task_id` 轮询 GET /s2s/v2.0/task/beard-style 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 running，这一阶段不消耗点数。
您也可以实现 Webhook，在 AI 任务成功或失败时收到通知。细节见 **[Webhook](../../../develop/webhook)** 一节。
> **警告：** 在任务保留期内轮询任务状态是必须做的。保留期内没有任何轮询请求，任务就会超时，即使任务已处理成功也一样，而您的点数照样会被消耗。
> **警告：** 若去查询已超时任务的状态，会收到 InvalidTaskId 错误。因此，执行 AI 任务之后，必须在保留期内持续轮询，直到状态变为 success 或 error。
4. **任务成功后取回结果**
引擎处理完您的输入文件、生成出图后，任务状态会变为 success，您会收到一张处理后图片的 URL。



---

## 文件规格与错误码
* 支持的格式与尺寸

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI 胡须造型生成 | 分辨率：长边 < 1024 脸宽 > 256 脸部姿态：-30 < yaw < 30，仅支持单人脸，需露出完整脸部 | < 10MB | jpg/jpeg |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| error_no_face | 源图中看不到脸 |
| error_src_face_too_small | 人脸过小 |
| error_inference | 胡须去除失败或胡须生成失败 |
| 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 功能 | 消耗点数 |
|  --- | --- |
| AI 胡须造型生成 V1.0 | 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_beard_style.yaml)

## V1.0

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