# AI 虛擬美甲 # 概述 AI 虛擬美甲 API 為對美甲感興趣的顧客提供了創新的線上體驗提升方式。它讓購物者虛擬呈現多種美甲風格，從人造與壓克力指甲、穿戴式指甲到凝膠設計。憑藉無限的顏色與質地選項，使用者可輕鬆在自然與人造指甲上探索不同外觀。此平台支援個人化的試戴，讓使用者輕鬆在風格間切換，並看見前後對比。這種無縫整合簡化了產品發現流程，並在購買前提供精準、互動的預覽，提升顧客信心。 ## 整合指南 本指南將引導您完成： AI 虛擬美甲 API 的工作流程： **需要認證：** `Authorization: Bearer YOUR_API_KEY` **工作流程步驟：** 1. **圖片上傳準備：** - 流程從準備手背圖片開始。 - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id` 。 - 使用提供的上傳網址，上傳含指甲的手背圖片。 2. **美甲設計設定選項：** - 先選擇合適的指甲顏色。您也可以依自己的喜好選擇自訂形狀。 3. **啟動 AI 任務並取得任務 ID：** - 透過 HTTP POST 請求，將上傳的圖片與所選特效設定傳送到 `/s2s/v2.0/task/nail-vto` 。 - 在回應中取得唯一的任務 ID，用以識別這次互動。 4. **輪詢任務狀態（持續檢查）：** - 使用取得的 `task_id` ，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/nail-vto/${task_id}` ）定期輪詢任務狀態。 - 持續監控： - `Task_status = "success"` （流程完成）。 - `Task_status = "error"` （視情況解決或重試）。 - 狀態轉為成功後，相應更新工作流程。 這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。 --- * API Playground 使用我們的官方 playground 進行互動式探索與測試： **API Playground：** [http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-nail-virtual-try-on/) --- * 認證 - 使用 **Bearer Token** 將您的 API key 納入請求標頭： ``` Authorization: Bearer YOUR_API_KEY ``` 您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。 1. 上傳圖片 您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。 * 上傳端點 ``` POST /s2s/v2.0/file ``` 或者，若您已有公開的圖片網址，可跳過此步驟。 --- 1. 準備特效範本 * 有四種不同的設定模式可用於此目的： 1. 自訂顏色，並與您目前的指甲外觀對齊 2. 使用預設設計與特定形狀，創造您的願景 3. 加入穿戴式指甲，並與您既有的原始指甲圖片連結 4. 提供符合的穿戴式指甲產品圖片連結 * 特效範本 JSON Schema ``` { "version": "1.0", "effect_type": "nail_polish", // valid values: ['nail_polish', 'press_on_nails'] "effects": [], "ref_file_ids": [] } ``` * 特效格式 - 指甲油 - 顏色 ``` { "sub_type": "color", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "color": "#ff0000", "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine'] "transparency": 0, // 0-100，適用於金屬以外的質感 "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 "shimmer_opacity": 0, // 0-100，適用於珍珠質感 "shimmer_size": 0, // 0-100，適用於 shimmer_coarse 與 shimmer_fine 質感 "textured_size": 0, // 0-100，適用於 textured 質感 } ``` - 指甲油 - 設計 ``` { "sub_type": "design", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "ref_file_url": "", // 選填；ref_file_id 或 ref_file_url 必須填寫其一，但只能選擇一項。 "ref_file_index": 0, // 除非選擇上傳，此欄位為選填。對應根節點下 ref_file_ids 的索引 "texture": "cream", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine'] "transparency": 0, // 0-100，僅適用於金屬以外的質感 "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 "shimmer_opacity": 0, // 0-100，適用於珍珠質感 "shimmer_size": 0, // 0-100，適用於 shimmer_coarse 與 shimmer_fine 質感 "textured_size": 0, // 0-100，適用於 textured 質感 } ``` - 穿戴式指甲 - 顏色 * 最新的形狀值可在以下網址找到：https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json ``` { "sub_type": "color", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "shape": "square_oval", // 請查閱 nails.json。有效值：['square_oval','square_square','square_squoval','squoval_oval','squoval_square','squoval_squoval','oval_oval','oval_square','oval_squoval','almond_oval','almond_square','almond_squoval','stiletto_oval','stiletto_square','stiletto_squoval], "length": 1.0, // 0.8-2.15，適用於 original 以外的形狀 "color": "#ff0000", "texture": "cream", // 其他形狀的有效值：['matte', 'cream', 'metallic'] "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0 // 0-100 } ``` - 穿戴式指甲 - 設計 ``` { "sub_type": "design", "finger": "index", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky'] "ref_file_url": "", // 選填；ref_file_id 或 ref_file_url 必須填寫其一，但只能選擇一項。 "ref_file_index": 0, // 除非選擇上傳，此欄位為選填。對應根節點下 ref_file_ids 的索引 "texture": "cream", // valid values: ['matte', 'cream', 'metallic'] "reflection": 0, // 0-100 "contrast": 0, // 0-100 "roughness": 0, // 0-100 } ``` * 特效範本設計邏輯 1. **偵測特效類型** （ `press_on_nails` 與 `nail_polish` ）。 2. **遍歷 `effects` 中的每個條目：** *若 `sub_type === "color"`* → 直接對應欄位，以預設值填入缺失的質地相關鍵。 *若 `sub_type === "design"`* → - 若使用者提供了 `ref_file_url` ，保留它並 **省略** `ref_file_index` 。 - 若使用者提供了索引（ `ref_file_index` ），確保 `ref_file_ids` 存在且索引有效；然後設定 `"ref_file_id": ref_file_ids[index]` （選填——某些後端期望原始索引，而非 id）。 1. **正規化數值範圍** – 將任何超出範圍的值限制在 0‑100 或長度限制內。 2. **加入缺失的選填鍵** 並設預設值，讓 schema 驗證通過。 3. 將最終物件 **序列化** 為 JSON（精簡格式，或為除錯使用美化格式）。 * 內容範例（可直接發送） ``` { "version": "1.0", "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg", "effect_type": "press_on_nails", "ref_file_ids": [ "Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud", "+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud" ], "effects": [ { "sub_type": "design", "finger": "thumb", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_index": 0 }, { "sub_type": "design", "finger": "index", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_index": 1 }, { "sub_type": "design", "finger": "middle", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png" }, { "sub_type": "design", "finger": "pinky", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png" }, { "sub_type": "design", "finger": "ring", "texture": "cream", "reflection": 100, "contrast": 50, "roughness": 0, "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png" } ] } ``` 2. 建立美甲 VTO 任務並輪詢結果 當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。 * 建立任務端點 ``` POST /s2s/v2.0/task/nail-vto ``` * 輪詢端點 ``` GET /s2s/v2.0/task/nail-vto/{task_id} ``` --- ## 檔案規格與錯誤 * AI 虛擬美甲規範 **支援的指甲視角** 單張指甲圖片，正面視角清晰且無遮擋。 | 項目 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 | | --- | --- | --- | --- | | 美甲設計圖片 - 指甲油 | * 271 px ≤ 寬度 ≤ 542 px* 522 px ≤ 高度 ≤ 1044 px* 至少 72ppi圖片會從中心套用，虛擬試色效果會依使用者指甲長度而變化。 | ≤ 1MB | png | | 美甲設計圖片 - 穿戴式指甲 | * 271 px ≤ 寬度 ≤ 542 px* 522 px ≤ 高度 ≤ 1044 px* 0.5 ≤ 圖片長寬比 (H/W) ≤ 3.5* 至少 72ppi圖片的內容、形狀與長度設定都用於生成虛擬試色效果。由於會偵測使用者指甲寬度以確保正確的圖片縮放，建議為每根指甲建立具有正確長寬比的個別圖片。請下載穿戴式指甲設計圖片範例，並參考圖片指引以取得更多細節。下載：[Nail_Design_Image_Guidelines.pdf](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/You_Cam_API_AI_Nail_Virtual_Try_On_Press_on_Nail_Design_Image_Guidelines_a229b51750.pdf) | ≤ 1MB​ | png（具透明背景） | 穿戴式指甲設計圖片範例： ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png) [](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png) --- **支援的手部視角** | 項目 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 | | --- | --- | --- | --- | | 使用者照片 | * 長邊 ≤ 2048* 短邊 ≥ 256 | ≤ 10MB | jpg/jpeg/png | * 輸入圖片僅支援一隻手 * 手掌面積最好至少為輸入圖片面積的一半 * 輸入圖片的長寬比最好為 1:1、3:4、4:3 * 手指的指甲不應被遮擋 * 指甲上最好沒有指甲貼片與指甲油 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg) --- * 錯誤代碼 | 錯誤代碼 | 說明 | | --- | --- | | error_nail_too_small | 指甲區域過小。 | | error_no_nail | 來源圖片中未偵測到指甲。 | * 環境與相依性 | 範例程式語言 / 工具 | 建議的執行環境版本 | | --- | --- | | 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 - Safari >= 13.1 | | PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_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 | --- ## JS Camera Kit --- ## 點數消耗 | 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_vto.yaml) ## V1.0 - [POST /s2s/v2.0/task/nail-vto](https://docs.perfectcorp.com/zh-tw/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto/post.md): 這個端點啟動虛擬美甲流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及特定的美甲特效設定。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。 - [GET /s2s/v2.0/task/nail-vto/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_nail_vto/v1.0/paths/~1s2s~1v2.0~1task~1nail-vto~1%7Btask_id%7D/get.md)