AI Nail Transfer
AI Nail Transfer接口是一套强大的生成式 AI 方案，专做虚拟试甲。依托 YouCam API 的先进 AI 模型与图像变换技术，用户可以把参考图上的任意美甲样式，逼真、精准地迁移到自己的手上。
从甲油胶、美甲彩绘、纯色甲面，到亮片、贝壳装饰、金属质感等繁复点缀，AI 都能把各式美甲风格以自然的高清虚拟预览还原出来。消费者下单前先试先看，心里有数。
对美妆品牌、美容院和美甲师来说，AI Nail Transfer接口是展示美甲作品的快招：客人看得过瘾、参与感强，满意度更高，沉浸式的虚拟体验还能把成交率拉上去。
本指南将带您走完全流程：
AI Nail Transfer接口的流程：
接口地址： /s2s/v2.0/task/ai-nail
需要鉴权： Authorization: Bearer YOUR_API_KEY
流程步骤：
- 准备图片上传：
- 先用 File 接口把手部图片准备好，接口为
/s2s/v2.0/file。
- 上传参考图：
- 用 File 接口（
/s2s/v2.0/file）上传一张带有您心仪美甲样式的参考图。想要效果最好，请确保十根手指的指甲都清楚可见。
- 发起 AI 任务并取得 Task ID：
- 用 HTTP POST 请求把上传好的图片送到
/s2s/v2.0/task/ai-nail。 - 响应会返回一个唯一的
task_id，用于标识本次调用。
- 轮询任务状态（持续检查）：
- 用取得的
task_id通过 HTTP GET 请求定期轮询任务状态（例如GET /task/${task_id}）。 - 持续留意：
Task_status = "success"（处理完成）。Task_status = "error"（视情况排查或重试）。- 状态转为 success 后，按流程继续往下走。
这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。
- 鉴权
- 请在请求头中以 Bearer Token 方式带上您的 API 密钥：
Authorization: Bearer YOUR_API_KEYAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。
- 上传图片
您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。
- 上传接口
POST /s2s/v2.0/file如果您已有公开可访问的图片 URL，这一步可以跳过。
- 上传参考图
您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。请确保十根手指的指甲都清楚可见，虚拟试戴效果才最准。
- 上传接口
POST /s2s/v2.0/file- 创建 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）。
支持的参考图
- 支持的格式与尺寸
| 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 |