# AI 美甲移轉 # 概述 AI 美甲移轉 API 是強大的生成式 AI 解決方案，用於虛擬美甲試色體驗。由 YouCam API 先進的 AI 模型與影像轉換技術驅動，使用者可從參考照片，即刻將任何理想的美甲設計移轉到自己的手上，具備卓越的真實感與精準度。 從凝膠指甲、美甲藝術與指甲油妝效，到亮片、貝殼點綴與金屬質地等精緻裝飾，AI 精準重現廣泛的美甲風格，呈現自然、高解析度的虛擬預覽。這讓消費者能在購買前自信地探索與呈現設計。 對美妝品牌、沙龍與美甲師而言，AI 美甲移轉 API 提供快速且引人入勝的方式，向客戶展示美甲設計，透過沉浸式的虛擬體驗，協助提升顧客互動、改善滿意度，並提高轉換率。 ![](https://plugins-media.makeupar.com/smb/blog/post/2022-11-24/8821ab6e-9852-4401-89df-dd6005fb81fc.jpg) ## 整合指南 本指南將引導您完成： AI 美甲移轉 API 的工作流程： **端點：** `/s2s/v2.0/task/ai-nail` **需要認證：** `Authorization: Bearer YOUR_API_KEY` **工作流程步驟：** 1. **圖片上傳準備：** - 流程從透過 File API 準備手部圖片開始，傳送到 `/s2s/v2.0/file` 。 1. **參考照片上傳：** - 透過 File API 上傳展示您理想美甲設計的參考照片到 `/s2s/v2.0/file` 。為獲得最佳結果，請確保所有指甲都清晰可見。 1. **啟動 AI 任務並取得任務 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"` （視情況解決或重試）。 - 狀態轉為成功後，相應更新工作流程。 這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。 --- * 認證 - 使用 **Bearer Token** 將您的 API key 納入請求標頭： ``` Authorization: Bearer YOUR_API_KEY ``` 您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。 * 1. 上傳圖片 您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。 * 上傳端點 ``` POST /s2s/v2.0/file ``` 或者，若您已有公開的圖片網址，可跳過此步驟。 --- * 1. 上傳參考照片 您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。請確保所有指甲可見，以獲得最精準的虛擬試色體驗。 * 上傳端點 ``` POST /s2s/v2.0/file ``` --- * 1. 建立 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）。 ![](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 美甲移轉 | 長邊 <= 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 | --- ## 點數消耗 | AI 功能 | 消耗的點數 | | --- | --- | | AI 美甲移轉 V1.0 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用標準的 'Bearer authentication'。請在標頭中放入您的 'API Key'：`Authorization:Bearer YOUR_API_KEY`。請注意 'Bearer' 與 'YOUR_API_KEY' 之間有一個空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 美甲移轉](https://docs.perfectcorp.com/_bundle/@l10n/zh-TW/reference/ai_nail_transfer.yaml) ## V1.0 - [POST /s2s/v2.0/task/ai-nail](https://docs.perfectcorp.com/zh-tw/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 或無法使用 - [GET /s2s/v2.0/task/ai-nail/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_nail_transfer/v1.0/paths/~1s2s~1v2.0~1task~1ai-nail~1%7Btask_id%7D/get.md)