# AI Nail Transfer

# 概览
AI Nail Transfer接口是一套强大的生成式 AI 方案，专做虚拟试甲。依托 YouCam API 的先进 AI 模型与图像变换技术，用户可以把参考图上的任意美甲样式，逼真、精准地迁移到自己的手上。
从甲油胶、美甲彩绘、纯色甲面，到亮片、贝壳装饰、金属质感等繁复点缀，AI 都能把各式美甲风格以自然的高清虚拟预览还原出来。消费者下单前先试先看，心里有数。
对美妆品牌、美容院和美甲师来说，AI Nail Transfer接口是展示美甲作品的快招：客人看得过瘾、参与感强，满意度更高，沉浸式的虚拟体验还能把成交率拉上去。
![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg)
## 接入指南
本指南将带您走完全流程：
AI Nail Transfer接口的流程：
**接口地址：** `/s2s/v2.0/task/ai-nail`
**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`
**流程步骤：**
1. **准备图片上传：**

- 先用 File 接口把手部图片准备好，接口为
`/s2s/v2.0/file`
。

1. **上传参考图：**

- 用 File 接口（
`/s2s/v2.0/file`
）上传一张带有您心仪美甲样式的参考图。想要效果最好，请确保十根手指的指甲都清楚可见。

1. **发起 AI 任务并取得 Task ID：**

- 用 HTTP POST 请求把上传好的图片送到
`/s2s/v2.0/task/ai-nail`
。
- 响应会返回一个唯一的
`task_id`
，用于标识本次调用。

1. **轮询任务状态（持续检查）：**

- 用取得的
`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. 上传图片

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


```
POST /s2s/v2.0/file
```
如果您已有公开可访问的图片 URL，这一步可以跳过。


---

*   1. 上传参考图

您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。请确保十根手指的指甲都清楚可见，虚拟试戴效果才最准。
* 上传接口


```
POST /s2s/v2.0/file
```


---

*   1. 创建 AI Nail Transfer任务并轮询结果

图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。
* 创建任务接口


```
POST /s2s/v2.0/task/ai-nail
```
* 轮询接口


```
GET /s2s/v2.0/task/ai-nail/{task_id}
```


---

## 文件规格与错误码
* AI Nail Transfer规格
**支持的手部图视角**
单张图片最多支持两只手，多出的手会被忽略。为了达到最佳检测效果，每只手至少占图片面积的 0.5%（FHD 约 102×102 px，2K 约 139×139 px，4K 约 204×204 px）。
![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png)
**支持的参考图**
![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_6_341b11df3d.png)
![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_2_86a47c1c26.png)



---

* 支持的格式与尺寸

| AI 功能 | 支持尺寸 | 支持文件大小 | 支持格式 |
|  --- | --- | --- | --- |
| AI Nail Transfer | 长边 <= 4096 | < 10MB | jpg/jpeg/png |

* 错误码

| 错误码 | 说明 |
|  --- | --- |
| exceed_max_filesize | 图片文件过大 |
| invalid_parameter | 输入参数缺失或格式有误 |
| error_download_image | 文件未上传完成，或图片 URL 无效 |
| error_inference | 推理失败，请检查输入图与参考图是否在支持范围内 |
| no_hand_detected | 源图中未检测到手 |

* 运行环境与依赖

| 示例代码语言 / 工具 | 建议运行时版本 |
|  --- | --- |
| 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- Safarin b\ |
| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) orn b_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 Nail Transfer V1.0 | 1 |



---

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 Nail Transfer](https://docs.perfectcorp.com/_bundle/@l10n/zh-CN/reference/ai_nail_transfer.yaml)

## V1.0

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