AI 美甲移轉
AI 美甲移轉 API 是強大的生成式 AI 解決方案，用於虛擬美甲試色體驗。由 YouCam API 先進的 AI 模型與影像轉換技術驅動，使用者可從參考照片，即刻將任何理想的美甲設計移轉到自己的手上，具備卓越的真實感與精準度。
從凝膠指甲、美甲藝術與指甲油妝效，到亮片、貝殼點綴與金屬質地等精緻裝飾，AI 精準重現廣泛的美甲風格，呈現自然、高解析度的虛擬預覽。這讓消費者能在購買前自信地探索與呈現設計。
對美妝品牌、沙龍與美甲師而言，AI 美甲移轉 API 提供快速且引人入勝的方式，向客戶展示美甲設計，透過沉浸式的虛擬體驗，協助提升顧客互動、改善滿意度，並提高轉換率。
本指南將引導您完成：
AI 美甲移轉 API 的工作流程：
端點： /s2s/v2.0/task/ai-nail
需要認證： Authorization: Bearer YOUR_API_KEY
工作流程步驟：
- 圖片上傳準備：
- 流程從透過 File API 準備手部圖片開始，傳送到
/s2s/v2.0/file。
- 參考照片上傳：
- 透過 File API 上傳展示您理想美甲設計的參考照片到
/s2s/v2.0/file。為獲得最佳結果，請確保所有指甲都清晰可見。
- 啟動 AI 任務並取得任務 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"（視情況解決或重試）。- 狀態轉為成功後，相應更新工作流程。
這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。
- 認證
- 使用 Bearer Token 將您的 API key 納入請求標頭：
Authorization: Bearer YOUR_API_KEY您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。
- 上傳圖片
您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。
- 上傳端點
POST /s2s/v2.0/file或者，若您已有公開的圖片網址，可跳過此步驟。
- 上傳參考照片
您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。請確保所有指甲可見，以獲得最精準的虛擬試色體驗。
- 上傳端點
POST /s2s/v2.0/file- 建立 AI 美甲移轉任務並輪詢結果
當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 success 或 error。
- 建立任務端點
POST /s2s/v2.0/task/ai-nail- 輪詢端點
GET /s2s/v2.0/task/ai-nail/{task_id}AI 美甲移轉規範
支援的手部視角
每張圖片最多支援兩隻手。額外的手會被忽略。為獲得最佳偵測效果，每隻手應佔圖片面積至少 0.5%（在 FHD 約為 102×102 px，2K 約為 139×139 px，4K 約為 204×204 px）。
支援的參考圖片
- 支援的格式與尺寸
| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |
|---|---|---|---|
| AI 美甲移轉 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png |
- 錯誤代碼
| 錯誤代碼 | 說明 |
|---|---|
| exceed_max_filesize | 圖片檔案過大 |
| invalid_parameter | 輸入參數缺失或格式錯誤 |
| error_download_image | 檔案上傳未完成，或圖片網址無效 |
| error_inference | 推論失敗，請確認輸入與參考圖片是否受支援 |
| no_hand_detected | 來源圖片中未偵測到手 |
- 環境與相依性
| 範例程式語言 / 工具 | 建議的執行環境版本 |
|---|---|
| cURL | - bash >= 3.2 - curl >= 7.58（現代 TLS/HTTP 支援） - jq >= 1.6（穩健的 JSON 解析） |
| Node.js（JavaScript） | Node >= 18（支援全域 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（支援 f-strings），requests >= 2.20.0 |
| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |