{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-CN/reference/ai_nail_transfer.yaml","sidebar":"sidebar-@l10n/zh-CN/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-CN/reference/ai_nail_transfer.yaml","settings":{"baseUrlPath":"/zh-cn/reference/ai_nail_transfer"},"disableAutoScroll":true,"seo":{"title":"AI Nail Transfer","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI Nail Transfer","version":"","description":"# 概览\nAI Nail Transfer接口是一套强大的生成式 AI 方案，专做虚拟试甲。依托 YouCam API 的先进 AI 模型与图像变换技术，用户可以把参考图上的任意美甲样式，逼真、精准地迁移到自己的手上。\n\n从甲油胶、美甲彩绘、纯色甲面，到亮片、贝壳装饰、金属质感等繁复点缀，AI 都能把各式美甲风格以自然的高清虚拟预览还原出来。消费者下单前先试先看，心里有数。\n\n对美妆品牌、美容院和美甲师来说，AI Nail Transfer接口是展示美甲作品的快招：客人看得过瘾、参与感强，满意度更高，沉浸式的虚拟体验还能把成交率拉上去。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg)\n\n## 接入指南\n本指南将带您走完全流程：\n\nAI Nail Transfer接口的流程：\n\n**接口地址：** `/s2s/v2.0/task/ai-nail`\n\n**需要鉴权：** `Authorization: Bearer YOUR_API_KEY`\n\n**流程步骤：**\n\n1. **准备图片上传：**\n- 先用 File 接口把手部图片准备好，接口为 `/s2s/v2.0/file`。\n\n2. **上传参考图：**\n- 用 File 接口（`/s2s/v2.0/file`）上传一张带有您心仪美甲样式的参考图。想要效果最好，请确保十根手指的指甲都清楚可见。\n\n1. **发起 AI 任务并取得 Task ID：**\n- 用 HTTP POST 请求把上传好的图片送到 `/s2s/v2.0/task/ai-nail`。\n- 响应会返回一个唯一的 `task_id`，用于标识本次调用。\n\n1. **轮询任务状态（持续检查）：**\n- 用取得的 `task_id` 通过 HTTP GET 请求定期轮询任务状态（例如 `GET /task/${task_id}`）。\n- 持续留意：\n- `Task_status = \"success\"`（处理完成）。\n- `Task_status = \"error\"`（视情况排查或重试）。\n- 状态转为 success 后，按流程继续往下走。\n\n这套规整的流程能顺畅对接用户输入、自动监控任务，并顺利取回结果。\n\n---\n\n* 鉴权\n- 请在请求头中以 **Bearer Token** 方式带上您的 API 密钥：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nAPI Key 可在 https://yce.makeupar.com/api-console/en/api-keys/ 获取。\n\n\n* 1. 上传图片\n\n您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。\n\n* 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n如果您已有公开可访问的图片 URL，这一步可以跳过。\n\n---\n\n* 2. 上传参考图\n\n您可以把文件直接上传到服务器，也可以在 AI 任务参数中提供有效的图片 URL。请确保十根手指的指甲都清楚可见，虚拟试戴效果才最准。\n\n* 上传接口\n\n```\nPOST /s2s/v2.0/file\n```\n\n---\n\n* 3. 创建 AI Nail Transfer任务并轮询结果\n\n图片和完整的特效参数备齐后即可创建任务。接口异步处理请求，您需要轮询任务状态，直到状态变为 `success` 或 `error`。\n\n* 创建任务接口\n\n```\nPOST /s2s/v2.0/task/ai-nail\n```\n\n* 轮询接口\n\n```\nGET /s2s/v2.0/task/ai-nail/{task_id}\n```\n\n---\n\n## 文件规格与错误码\n\n* AI Nail Transfer规格\n\n    **支持的手部图视角**\n\n    单张图片最多支持两只手，多出的手会被忽略。为了达到最佳检测效果，每只手至少占图片面积的 0.5%（FHD 约 102×102 px，2K 约 139×139 px，4K 约 204×204 px）。\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_bare_nails_014_f6451b0343.png)\n\n\n    **支持的参考图**\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_6_341b11df3d.png)\n\n    ![](https://plugins-media.makeupar.com/strapi/assets/small_webp_ref_2_86a47c1c26.png)\n\n---\n\n* 支持的格式与尺寸\n\n|AI 功能|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n| AI Nail Transfer | 长边 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 错误码\n\n| 错误码 | 说明 |\n| ---- | ---- |\n| exceed_max_filesize | 图片文件过大 |\n| invalid_parameter | 输入参数缺失或格式有误 |\n| error_download_image | 文件未上传完成，或图片 URL 无效 |\n| error_inference | 推理失败，请检查输入图与参考图是否在支持范围内 |\n| no_hand_detected | 源图中未检测到手 |\n\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>- curl >= 7.58 (modern TLS/HTTP support)</br>- jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>- Firefox >= 74</br>- Safarin b\\ |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) orn b\\_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n\n## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI Nail Transfer V1.0 | 1 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.126"},"lang":"zh-CN","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-cn/reference/ai_nail_transfer","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}