{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-TW/reference/ai_nail_transfer.yaml","sidebar":"sidebar-@l10n/zh-TW/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-TW/reference/ai_nail_transfer.yaml","settings":{"baseUrlPath":"/zh-tw/reference/ai_nail_transfer"},"disableAutoScroll":true,"seo":{"title":"AI 美甲移轉","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 美甲移轉","version":"","description":"# 概述\nAI 美甲移轉 API 是強大的生成式 AI 解決方案，用於虛擬美甲試色體驗。由 YouCam API 先進的 AI 模型與影像轉換技術驅動，使用者可從參考照片，即刻將任何理想的美甲設計移轉到自己的手上，具備卓越的真實感與精準度。\n\n從凝膠指甲、美甲藝術與指甲油妝效，到亮片、貝殼點綴與金屬質地等精緻裝飾，AI 精準重現廣泛的美甲風格，呈現自然、高解析度的虛擬預覽。這讓消費者能在購買前自信地探索與呈現設計。\n\n對美妝品牌、沙龍與美甲師而言，AI 美甲移轉 API 提供快速且引人入勝的方式，向客戶展示美甲設計，透過沉浸式的虛擬體驗，協助提升顧客互動、改善滿意度，並提高轉換率。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg)\n\n## 整合指南\n本指南將引導您完成：\n\nAI 美甲移轉 API 的工作流程：\n\n**端點：** `/s2s/v2.0/task/ai-nail`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n- 流程從透過 File API 準備手部圖片開始，傳送到 `/s2s/v2.0/file`。\n\n2. **參考照片上傳：**\n- 透過 File API 上傳展示您理想美甲設計的參考照片到 `/s2s/v2.0/file`。為獲得最佳結果，請確保所有指甲都清晰可見。\n\n1. **啟動 AI 任務並取得任務 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- 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。\n\n* 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 2. 上傳參考照片\n\n您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。請確保所有指甲可見，以獲得最精準的虛擬試色體驗。\n\n* 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n---\n\n* 3. 建立 AI 美甲移轉任務並輪詢結果\n\n當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `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 美甲移轉規範\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 美甲移轉 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n| ---- | ---- |\n| exceed_max_filesize | 圖片檔案過大 |\n| invalid_parameter | 輸入參數缺失或格式錯誤 |\n| error_download_image | 檔案上傳未完成，或圖片網址無效 |\n| error_inference | 推論失敗，請確認輸入與參考圖片是否受支援 |\n| no_hand_detected | 來源圖片中未偵測到手 |\n\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2</br>- curl >= 7.58（現代 TLS/HTTP 支援）</br>- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 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（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 美甲移轉 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-TW","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-tw/reference/ai_nail_transfer","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}