{
  "openapi": "3.0.0",
  "info": {
    "title": "AI 虛擬美甲",
    "description": "# 概述\nAI 虛擬美甲 API 為對美甲感興趣的顧客提供了創新的線上體驗提升方式。它讓購物者虛擬呈現多種美甲風格，從人造與壓克力指甲、穿戴式指甲到凝膠設計。憑藉無限的顏色與質地選項，使用者可輕鬆在自然與人造指甲上探索不同外觀。此平台支援個人化的試戴，讓使用者輕鬆在風格間切換，並看見前後對比。這種無縫整合簡化了產品發現流程，並在購買前提供精準、互動的預覽，提升顧客信心。\n\n## 整合指南\n本指南將引導您完成：\n\nAI 虛擬美甲 API 的工作流程：\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n    - 流程從準備手背圖片開始。\n    - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id`。\n    - 使用提供的上傳網址，上傳含指甲的手背圖片。\n\n2. **美甲設計設定選項：**\n    - 先選擇合適的指甲顏色。您也可以依自己的喜好選擇自訂形狀。\n\n3. **啟動 AI 任務並取得任務 ID：**\n    - 透過 HTTP POST 請求，將上傳的圖片與所選特效設定傳送到 `/s2s/v2.0/task/nail-vto`。\n    - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n4. **輪詢任務狀態（持續檢查）：**\n    - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/nail-vto/${task_id}`）定期輪詢任務狀態。\n    - 持續監控：\n        - `Task_status = \"success\"`（流程完成）。\n        - `Task_status = \"error\"`（視情況解決或重試）。\n    - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[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/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n    ```\n    Authorization: Bearer YOUR_API_KEY\n    ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n\n1. 上傳圖片\n\n    您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n    * 上傳端點\n\n        ```\n        POST /s2s/v2.0/file\n        ```\n\n    或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n2. 準備特效範本\n\n    * 有四種不同的設定模式可用於此目的：\n        1. 自訂顏色，並與您目前的指甲外觀對齊\n        2. 使用預設設計與特定形狀，創造您的願景\n        3. 加入穿戴式指甲，並與您既有的原始指甲圖片連結\n        4. 提供符合的穿戴式指甲產品圖片連結 \n\n    * 特效範本 JSON Schema\n        ```\n        {\n            \"version\": \"1.0\",\n            \"effect_type\": \"nail_polish\", // valid values: ['nail_polish', 'press_on_nails']\n            \"effects\": [],\n            \"ref_file_ids\": []\n        }\n        ```\n\n        * 特效格式\n            - 指甲油 - 顏色\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100，適用於金屬以外的質感\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100，適用於珍珠質感\n                \"shimmer_size\": 0, // 0-100，適用於 shimmer_coarse 與 shimmer_fine 質感\n                \"textured_size\": 0, // 0-100，適用於 textured 質感\n            }\n            ```\n\n            - 指甲油 - 設計\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // 選填；ref_file_id 或 ref_file_url 必須填寫其一，但只能選擇一項。\n                \"ref_file_index\": 0, // 除非選擇上傳，此欄位為選填。對應根節點下 ref_file_ids 的索引\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic', 'jelly', 'sheer', 'pearl', 'textured', 'shimmer_coarse', 'shimmer_fine']\n                \"transparency\": 0, // 0-100，僅適用於金屬以外的質感\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n                \"shimmer_opacity\": 0, // 0-100，適用於珍珠質感\n                \"shimmer_size\": 0, // 0-100，適用於 shimmer_coarse 與 shimmer_fine 質感\n                \"textured_size\": 0, // 0-100，適用於 textured 質感\n            }\n\n            ```\n\n            - 穿戴式指甲 - 顏色\n            * 最新的形狀值可在以下網址找到：https://plugins-media.makeupar.com/wcm-saas/shapes/nails.json\n            ```\n            {\n                \"sub_type\": \"color\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"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],\n                \"length\": 1.0, // 0.8-2.15，適用於 original 以外的形狀\n                \"color\": \"#ff0000\",\n                \"texture\": \"cream\", // 其他形狀的有效值：['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0 // 0-100\n            }\n            ```\n\n            - 穿戴式指甲 - 設計\n            ```\n            {\n                \"sub_type\": \"design\",\n                \"finger\": \"index\", // valid values: ['thumb', 'index', 'middle', 'ring', 'pinky']\n                \"ref_file_url\": \"\",  // 選填；ref_file_id 或 ref_file_url 必須填寫其一，但只能選擇一項。\n                \"ref_file_index\": 0, // 除非選擇上傳，此欄位為選填。對應根節點下 ref_file_ids 的索引\n                \"texture\": \"cream\", // valid values: ['matte', 'cream', 'metallic']\n                \"reflection\": 0, // 0-100\n                \"contrast\": 0, // 0-100\n                \"roughness\": 0, // 0-100\n            }\n\n            ```\n\n   * 特效範本設計邏輯\n\n        1. **偵測特效類型**（`press_on_nails` 與 `nail_polish`）。\n        2. **遍歷 `effects` 中的每個條目：**\n\n        *若 `sub_type === \"color\"`* → 直接對應欄位，以預設值填入缺失的質地相關鍵。\n        *若 `sub_type === \"design\"`* →\n        - 若使用者提供了 `ref_file_url`，保留它並**省略** `ref_file_index`。\n        - 若使用者提供了索引（`ref_file_index`），確保 `ref_file_ids` 存在且索引有效；然後設定 `\"ref_file_id\": ref_file_ids[index]`（選填——某些後端期望原始索引，而非 id）。\n\n        1. **正規化數值範圍** – 將任何超出範圍的值限制在 0‑100 或長度限制內。\n        2. **加入缺失的選填鍵**並設預設值，讓 schema 驗證通過。\n        3. 將最終物件**序列化**為 JSON（精簡格式，或為除錯使用美化格式）。\n\n   * 內容範例（可直接發送）\n        ```\n        {\n        \"version\": \"1.0\",\n        \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/nail_user_photo_01_27d4260646.jpg\",\n        \"effect_type\": \"press_on_nails\",\n        \"ref_file_ids\": [\n            \"Ks3kh+1nPpVNm8iJb5374CWtBzkT4B44NPJwXbBKqVxfjK3xgCQ+hRt9MJXBFaud\",\n            \"+Z7PSjuzigvsc3S/Yli1A4WN7c3J6NJHFqK2iUlqD2BfjK3xgCQ+hRt9MJXBFaud\"\n        ],\n        \"effects\": [\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"thumb\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 0\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"index\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_index\": 1\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"middle\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_3_9ce2ddc47a.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"pinky\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_5_f6e46dd56f.png\"\n            },\n            {\n            \"sub_type\": \"design\",\n            \"finger\": \"ring\",\n            \"texture\": \"cream\",\n            \"reflection\": 100,\n            \"contrast\": 50,\n            \"roughness\": 0,\n            \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/press_on_nail_06_4_2103ca8cac.png\"\n            }\n        ]\n        }\n        ```\n\n\n3. 建立美甲 VTO 任務並輪詢結果\n\n    當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n    * 建立任務端點\n\n        ```\n        POST /s2s/v2.0/task/nail-vto\n        ```\n\n    * 輪詢端點\n\n        ```\n        GET /s2s/v2.0/task/nail-vto/{task_id}\n        ```\n\n---\n\n## 檔案規格與錯誤\n\n* AI 虛擬美甲規範\n\n**支援的指甲視角**\n單張指甲圖片，正面視角清晰且無遮擋。\n\n| 項目 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| --- | --- | --- | --- |\n| 美甲設計圖片 - 指甲油 | *   271 px ≤ 寬度 ≤ 542 px<br>*   522 px ≤ 高度 ≤ 1044 px<br>*   至少 72ppi<br>圖片會從中心套用，虛擬試色效果會依使用者指甲長度而變化。 | ≤ 1MB | png |\n| 美甲設計圖片 - 穿戴式指甲 | *   271 px ≤ 寬度 ≤ 542 px<br>*   522 px ≤ 高度 ≤ 1044 px<br>*   0.5 ≤ 圖片長寬比 (H/W) ≤ 3.5<br>*   至少 72ppi<br>圖片的內容、形狀與長度設定都用於生成虛擬試色效果。<br>由於會偵測使用者指甲寬度以確保正確的圖片縮放，建議為每根指甲建立具有正確長寬比的個別圖片。<br>請下載穿戴式指甲設計圖片範例，並參考圖片指引以取得更多細節。下載：[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（具透明背景） |\n\n穿戴式指甲設計圖片範例：\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_press_on_nail_06_5_f6e46dd56f.png)\n\n[<img src=\"https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png\" width=\"60\"/>](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/youcamapi_press_on_nail_design_image_sample_de6bd64f20.png)\n\n---\n\n**支援的手部視角**\n\n| 項目 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |\n| --- | --- | --- | --- |\n| 使用者照片 | *   長邊 ≤ 2048<br>*   短邊 ≥ 256 | ≤ 10MB | jpg/jpeg/png |\n* 輸入圖片僅支援一隻手\n* 手掌面積最好至少為輸入圖片面積的一半\n* 輸入圖片的長寬比最好為 1:1、3:4、4:3\n* 手指的指甲不應被遮擋\n* 指甲上最好沒有指甲貼片與指甲油\n\n![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_nail_user_photo_02_fdba1848d6.jpg)\n\n---\n\n* 錯誤代碼\n\n| 錯誤代碼 | 說明 |\n|  ----  | ----  |\n| error_nail_too_small | 指甲區域過小。 |\n| error_no_nail\t| 來源圖片中未偵測到指甲。 |\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>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_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## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬美甲 V1.0 | 1 |\n\n---\n",
    "version": "",
    "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api",
    "contact": {
      "email": "YouCamOnlineEditor_API@perfectcorp.com"
    },
    "license": {
      "name": "Privacy policy",
      "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api"
    }
  },
  "servers": [
    {
      "url": "https://yce-api-01.makeupar.com"
    }
  ],
  "tags": [
    {
      "name": "V1.0",
      "description": "使用 AI 處理，為上傳的圖片生成指甲油與穿戴式指甲的虛擬試色體驗。"
    }
  ],
  "paths": {
    "/s2s/v2.0/task/nail-vto": {
      "post": {
        "summary": "執行 AI 虛擬美甲任務。",
        "description": "這個端點啟動虛擬美甲流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及特定的美甲特效設定。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。\n",
        "tags": [
          "V1.0"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NailVtoTaskRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任務執行成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BasicRunTaskResponseV2"
                }
              }
            }
          },
          "400": {
            "description": "任務執行失敗",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/RunError"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          }
        }
      }
    },
    "/s2s/v2.0/task/nail-vto/{task_id}": {
      "get": {
        "summary": "查詢 AI 虛擬美甲任務的狀態。",
        "tags": [
          "V1.0"
        ],
        "security": [
          {
            "BearerAuthenticationV2": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
            },
            "description": "要查詢的任務 ID"
          }
        ],
        "responses": {
          "200": {
            "description": "成功查詢任務狀態",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskStatusResponseV2"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidTaskId"
          },
          "401": {
            "$ref": "#/components/responses/InvalidApiKey"
          },
          "500": {
            "$ref": "#/components/responses/TaskTimeout"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuthenticationV2": {
        "type": "http",
        "scheme": "bearer",
        "description": "使用標準的 'Bearer authentication'。請在標頭中放入您的 'API Key'：`Authorization:Bearer YOUR_API_KEY`。請注意 'Bearer' 與 'YOUR_API_KEY' 之間有一個空格。"
      }
    },
    "schemas": {
      "NailVtoTaskRequest": {
        "title": "虛擬美甲任務請求",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/BasicRunTaskV2WithMultiRef"
          },
          {
            "type": "object",
            "required": [
              "version",
              "effect_type",
              "effects"
            ],
            "properties": {
              "version": {
                "type": "string",
                "description": "美甲特效規範的版本。\n除非另有指定，預設為 `\"1.0\"`。\n",
                "default": "1.0",
                "example": "1.0"
              },
              "effect_type": {
                "type": "string",
                "enum": [
                  "nail_polish",
                  "press_on_nails"
                ],
                "example": "nail_polish"
              },
              "effects": {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorMetallicEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorPearlEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorShimmerEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishColorTexturedEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignMetallicEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignPearlEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignShimmerEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoNailPolishDesignTexturedEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoPressOnNailsColorEffect"
                    },
                    {
                      "$ref": "#/components/schemas/NailVtoPressOnNailsDesignEffect"
                    }
                  ]
                }
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorBaseEffect": {
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "color",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "color"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "color": {
            "type": "string",
            "pattern": "^#([A-Fa-f0-9]{6})$"
          },
          "texture": {
            "type": "string"
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "NailVtoNailPolishColorEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲彩繪 - 顏色 - 一般",
            "type": "object",
            "required": [
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "matte",
                  "cream",
                  "jelly",
                  "sheer"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorMetallicEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲彩繪 - 顏色 - 金屬",
            "type": "object",
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "metallic"
                ]
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorPearlEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲彩繪 - 顏色 - 珍珠",
            "type": "object",
            "required": [
              "shimmer_opacity",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "pearl"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "shimmer_opacity": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorShimmerEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲彩繪 - 顏色 - 閃亮",
            "type": "object",
            "required": [
              "shimmer_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "shimmer_coarse",
                  "shimmer_fine"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "shimmer_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishColorTexturedEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishColorBaseEffect"
          },
          {
            "title": "指甲彩繪 - 顏色 - 質感",
            "type": "object",
            "required": [
              "textured_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "textured"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "textured_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignBaseEffect": {
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "design"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "ref_file_url": {
            "type": "string",
            "description": "要達成 Nail Polish - Design 或 Press on Nails - Design 特效，您需要使用特定的設計圖片。您可以提供直接指向檔案的網址（ref_file_url），或提供一個索引（ref_file_index），對應您系統中根節點下的 'ref_file_ids'。您必須提供 'ref_file_url' 或 'ref_file_index' 其中之一，且一次只能選擇一個。\n"
          },
          "ref_file_index": {
            "type": "integer",
            "description": "若您想透過 File API 上傳設計圖片，以達成 Nail Polish - Design 或 Press on Nails - Design 特效，您應使用 File API 上傳您的圖片。上傳後，取得其檔案 ID 並加入 `ref_file_ids` 陣列，並以 `ref_file_index` 指定索引。索引對應根節點下的 'ref_file_ids'\n"
          },
          "texture": {
            "type": "string"
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "NailVtoNailPolishDesignEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲彩繪 - 設計 - 一般",
            "type": "object",
            "required": [
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "matte",
                  "cream",
                  "jelly",
                  "sheer"
                ]
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignMetallicEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲彩繪 - 設計 - 金屬",
            "type": "object",
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "metallic"
                ]
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignPearlEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲彩繪 - 設計 - 珍珠",
            "type": "object",
            "required": [
              "shimmer_opacity",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "pearl"
                ]
              },
              "shimmer_opacity": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignShimmerEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲彩繪 - 設計 - 閃亮",
            "type": "object",
            "required": [
              "shimmer_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "shimmer_coarse",
                  "shimmer_fine"
                ]
              },
              "shimmer_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoNailPolishDesignTexturedEffect": {
        "allOf": [
          {
            "$ref": "#/components/schemas/NailVtoNailPolishDesignBaseEffect"
          },
          {
            "title": "指甲彩繪 - 設計 - 質感",
            "type": "object",
            "required": [
              "textured_size",
              "transparency"
            ],
            "properties": {
              "texture": {
                "type": "string",
                "enum": [
                  "textured"
                ]
              },
              "textured_size": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              },
              "transparency": {
                "type": "integer",
                "minimum": 0,
                "maximum": 100
              }
            }
          }
        ]
      },
      "NailVtoPressOnNailsColorEffect": {
        "title": "貼片指甲 - 顏色",
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "shape",
          "length",
          "color",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "color"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "shape": {
            "type": "string",
            "enum": [
              "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": {
            "type": "number",
            "minimum": 0.8,
            "maximum": 2.15
          },
          "color": {
            "type": "string",
            "pattern": "^#([A-Fa-f0-9]{6})$"
          },
          "texture": {
            "type": "string",
            "enum": [
              "matte",
              "cream",
              "metallic"
            ]
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "NailVtoPressOnNailsDesignEffect": {
        "title": "貼片指甲 - 設計",
        "type": "object",
        "required": [
          "sub_type",
          "finger",
          "texture",
          "reflection",
          "contrast",
          "roughness"
        ],
        "properties": {
          "sub_type": {
            "type": "string",
            "enum": [
              "design"
            ]
          },
          "finger": {
            "type": "string",
            "enum": [
              "thumb",
              "index",
              "middle",
              "ring",
              "pinky"
            ]
          },
          "ref_file_url": {
            "type": "string",
            "description": "必須填寫 'ref_file_id' 或 'ref_file_url' 其中之一，且只能選擇一個。"
          },
          "ref_file_index": {
            "type": "integer",
            "description": "除非選擇上傳，此欄位為選填。對應根節點下 'ref_file_ids' 的索引"
          },
          "texture": {
            "type": "string",
            "enum": [
              "matte",
              "cream",
              "metallic"
            ]
          },
          "reflection": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "contrast": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          },
          "roughness": {
            "type": "integer",
            "minimum": 0,
            "maximum": 100
          }
        }
      },
      "BasicRunTaskV2SrcFileUrl": {
        "type": "object",
        "required": [
          "src_file_url"
        ],
        "properties": {
          "src_file_url": {
            "type": "string",
            "description": "要執行任務的檔案網址。該網址應可公開存取。",
            "example": "https://example.com/selfie.jpg"
          }
        }
      },
      "BasicRunTaskV2RefFileUrls": {
        "type": "object",
        "properties": {
          "ref_file_urls": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "description": "執行任務所用參考檔案的多個網址。該網址需可公開存取。",
              "example": "https://example.com/accessory.jpg"
            }
          }
        }
      },
      "BasicRunTaskV2RefFileIds": {
        "type": "object",
        "properties": {
          "ref_file_ids": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "string",
              "description": "執行任務所用參考檔案的多個 ID。來自上傳檔案 API 的檔案 ID。",
              "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
            }
          }
        }
      },
      "BasicRunTaskV2SrcFileId": {
        "type": "object",
        "required": [
          "src_file_id"
        ],
        "properties": {
          "src_file_id": {
            "type": "string",
            "description": "要執行任務的檔案 ID。檔案 ID 來自上傳檔案 API。",
            "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
          }
        }
      },
      "BasicRunTaskV2WithMultiRef": {
        "title": "BasicRunTaskV2WithRef",
        "anyOf": [
          {
            "allOf": [
              {
                "title": "Run task with src file url & ref file urls"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileUrls"
              }
            ]
          },
          {
            "allOf": [
              {
                "title": "Run task with src file url & ref file IDs"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileIds"
              }
            ]
          },
          {
            "allOf": [
              {
                "title": "Run task with src file ID & ref file urls"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileUrls"
              }
            ]
          },
          {
            "allOf": [
              {
                "title": "Run task with src file ID & ref file IDs"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
              },
              {
                "$ref": "#/components/schemas/BasicRunTaskV2RefFileIds"
              }
            ]
          }
        ]
      },
      "BasicRunTaskResponseV2": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "回應狀態",
            "example": 200
          },
          "data": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "這個任務的 ID。任務結果可以此 ID 查詢，有效期限 24 小時。",
                "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
              }
            }
          }
        }
      },
      "RunError": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "回應狀態",
            "example": 400
          },
          "error": {
            "type": "string",
            "description": "錯誤訊息",
            "example": "The operation could not be completed"
          },
          "error_code": {
            "type": "string",
            "enum": [
              "InvalidParameters",
              "CreditInsufficiency",
              "InvalidStyleGroup",
              "InvalidStyle",
              "BadRequest"
            ],
            "description": "錯誤代碼：\n* InvalidParameters - 請求參數無效\n* CreditInsufficiency - 點數不足，無法執行\n* BadRequest - 非預期的請求參數\n* InvalidStyleGroup - 風格群組 id 無效\n* InvalidStyle - 風格 id 無效\n"
          }
        }
      },
      "EngineErrorCode": {
        "type": "string",
        "nullable": true,
        "enum": [
          "error_exceed_max_image_size",
          "exceed_max_filesize",
          "invalid_parameter",
          "error_download_image",
          "error_download_mask",
          "error_decode_image",
          "error_decode_mask",
          "error_nsfw_content_detected",
          "error_no_face",
          "error_pose",
          "error_face_parsing",
          "error_inference",
          "exceed_nsfw_retry_limits",
          "error_upload",
          "unknown_internal_error"
        ],
        "description": "錯誤：\n- \\`error_exceed_max_image_size\\`  - 輸入圖片尺寸超過上限\n- \\`exceed_max_filesize\\` - 輸入檔案大小超過上限\n- \\`invalid_parameter\\` - 參數值無效\n- \\`error_download_image\\` - 下載來源圖片錯誤\n- \\`error_download_mask\\` - 下載遮罩圖片錯誤\n- \\`error_decode_image\\` - 解析來源圖片錯誤\n- \\`error_decode_mask\\` - 解析遮罩圖片錯誤\n- \\`error_nsfw_content_detected\\` - 在來源圖片中偵測到 NSFW 內容\n- \\`error_no_face\\` - 來源圖片未偵測到臉部\n- \\`error_pose\\` - 無法偵測來源圖片的姿势\n- \\`error_face_parsing\\` - 無法對來源圖片進行臉部分割\n- \\`error_inference\\` - 推論流程錯誤\n- \\`exceed_nsfw_retry_limits\\` - 超過重試上限以避免產生 NSFW 圖片\n- \\`error_upload\\` - 上傳結果圖片錯誤\n- \\`unknown_internal_error\\` - 其他"
      },
      "TaskStatusResponseBodySingleUrlResultsV2": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "下載這個結果的網址。有效期限 2 小時",
            "example": "https://example.com/sample-result-url"
          }
        }
      },
      "TaskStatusResponseV2": {
        "type": "object",
        "properties": {
          "status": {
            "type": "integer",
            "description": "回應狀態",
            "example": 200
          },
          "data": {
            "type": "object",
            "properties": {
              "task_status": {
                "type": "string",
                "enum": [
                  "running",
                  "success",
                  "error"
                ],
                "description": "這個任務的狀態"
              },
              "error": {
                "$ref": "#/components/schemas/EngineErrorCode"
              },
              "error_message": {
                "type": "string",
                "description": "錯誤的詳細說明"
              },
              "results": null
            }
          }
        },
        "$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
      }
    },
    "responses": {
      "InvalidApiKey": {
        "description": "API 金鑰無效或缺失",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 401,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Invalid API key"
                }
              }
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "請求過多",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 429,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Too many requests"
                }
              }
            }
          }
        }
      },
      "InvalidTaskId": {
        "description": "任務 ID 無效",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 400,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Invalid task ID"
                }
              }
            }
          }
        }
      },
      "TaskTimeout": {
        "description": "任務執行逾時",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "integer",
                  "example": 500,
                  "description": "回應狀態"
                },
                "error": {
                  "type": "string",
                  "example": "Task execution timed out"
                }
              }
            }
          }
        }
      }
    }
  }
}