跳转到内容

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/

  • 認證
  • 使用 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
圖片會從中心套用，虛擬試色效果會依使用者指甲長度而變化。		≤ 1MBpng
美甲設計圖片 - 穿戴式指甲* 271 px ≤ 寬度 ≤ 542 px
* 522 px ≤ 高度 ≤ 1044 px
* 0.5 ≤ 圖片長寬比 (H/W) ≤ 3.5
* 至少 72ppi
圖片的內容、形狀與長度設定都用於生成虛擬試色效果。
由於會偵測使用者指甲寬度以確保正確的圖片縮放，建議為每根指甲建立具有正確長寬比的個別圖片。
請下載穿戴式指甲設計圖片範例，並參考圖片指引以取得更多細節。下載：Nail_Design_Image_Guidelines.pdf		≤ 1MB​png（具透明背景）

穿戴式指甲設計圖片範例：

支援的手部視角

項目支援的尺寸支援的檔案大小支援的格式
使用者照片* 長邊 ≤ 2048
* 短邊 ≥ 256		≤ 10MBjpg/jpeg/png
  • 輸入圖片僅支援一隻手
  • 手掌面積最好至少為輸入圖片面積的一半
  • 輸入圖片的長寬比最好為 1:1、3:4、4:3
  • 手指的指甲不應被遮擋
  • 指甲上最好沒有指甲貼片與指甲油

  • 錯誤代碼
錯誤代碼說明
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
PHPPHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json
PythonPython >= 3.10（支援 f-strings），requests >= 2.20.0
JavaJava 11+（支援 HttpClient），Jackson Databind >= 2.12.0

JS Camera Kit

點數消耗

AI 功能消耗的點數
AI 虛擬美甲 V1.01
下载 OpenAPI 描述
ai_nail_vto.json
ai_nail_vto.yaml
概述
电子邮件
YouCamOnlineEditor_API@perfectcorp.com
许可证
Privacy policy
服务条款
语言
服务器
https://yce-api-01.makeupar.com