{ "openapi": "3.0.0", "info": { "title": "AI 虛擬試妝", "description": "# 概述\nAI 虛擬試妝 API 以我們專利的臉部分析技術為基礎，提供強大且極其逼真的虛擬改造型體驗。此服務讓您的應用程式能以前所未有的自訂能力，在使用者提供的自拍圖片上套用栩栩如生的彩妝特效。\n\n**主要功能：**\n* **極其逼真的渲染：** 運用革命性的 3D 人臉 AI 技術，達成最真實的改造型效果。\n* **專利技術：** 由無抖動、無延遲的深度學習演算法驅動，針對所有年齡與族裔最佳化。\n* **即時精準：** 超精準的臉部追蹤，可適應各種光線條件。\n* **栩栩如生的對應：** 精確對應現實產品的顏色、質地（從 matte 到 metallic）與妝效。\n\n* 核心概念\n\n * 色彩混合\n我們的 AI 使用深度學習，精確對應現實彩妝產品的顏色。這確保消費者能確信他們看到的虛擬顏色，就是他們打算購買產品的真實顏色。\n\n * 質地與妝效對應\n此技術模擬逼真的質地與妝效，提供高度準確的改造型體驗。從 matte 到 metallic、shimmer 到 satin，AI 運用先進演算法即時無縫渲染這些特效。\n\n * 光線平衡\n智慧 3D AI 引擎會偵測使用者照片或影片串流中的光線條件。它會校正圖片以達到栩栩如生的彩妝套用，無論環境如何，都確保一致且高品質的結果。\n\n---\n\n## 整合指南\n\n彩妝虛擬試戴服務以非同步任務運作。您必須先提供圖片網址與期望特效清單，啟動彩妝處理任務。伺服器會回傳 `task_id`。接著您定期輪詢狀態端點，以取得最終結果或任何錯誤。\n\n* **端點：** `/v2.0/task/makeup-vto`\n* **認證：** 所有請求都需要 `Authorization: Bearer `\n* **工作流程：**\n 1. **準備自拍：** 上傳圖片，或使用既有臉部圖片的檔案網址。\n 1. **啟動任務（`POST`）：** 提交您的圖片 id/網址與彩妝設定。\n 1. **取得任務 ID：** 從回應中取得 `task_id`。\n 1. **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-makeup-virtual-try-on/)\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n ```\n Authorization: Bearer \n ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n* 1. 上傳自拍\n 您可以透過兩種方式之一提供來源圖片：\n\n - **使用現有的公開圖片網址**\n 無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。\n\n - **透過 File API 上傳**\n 使用端點：\n ```\n POST /s2s/v2.0/file\n ```\n 這會回傳用於後續任務執行的 `file_id`。\n\n - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。

\n 在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。\n\n > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。\n\n\n* 2. 啟動彩妝任務\n\n`POST /s2s/v2.0/task/makeup-vto`\n\n在提供的圖片上啟動新的虛擬彩妝任務。這個端點為非同步，會回傳 `task_id`。\n\n * 請求標頭\n\n| 標頭 | 值 |\n|--------|-------|\n| Content-Type | `application/json` |\n| Authorization | `Bearer YOUR_API_KEY` |\n\n * 請求內容範例\n```json\n{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_1_202b6bf6e6.jpg\",\n \"effects\": [\n {\n \"category\": \"blush\",\n \"pattern\": { \"name\": \"2colors6\" },\n \"palettes\": [\n { \"color\": \"#FF0000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n { \"color\": \"#F2A53E\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n ]\n },\n {\n \"category\": \"eye_liner\",\n \"pattern\": { \"name\": \"3colors5\" },\n \"palettes\": [\n { \"color\": \"#000000\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n { \"color\": \"#BA0656\", \"texture\": \"matte\", \"colorIntensity\": 50 },\n { \"color\": \"#089085\", \"texture\": \"matte\", \"colorIntensity\": 50 }\n ]\n }\n ],\n \"version\": \"1.0\"\n}\n```\n\n * 請求內容 Schema\n\n| 欄位 | 類型 | 說明 |\n|-------|------|---------|\n| `src_file_url` | string（URL） | 要處理的自拍圖片之可公開存取的網址。 |\n| `effects` | Effect 陣列 | 要套用的彩妝特效物件陣列。細節請參考[彩妝特效 Schema](#makeup-effect-schemas)。 |\n| `version` | string | 特效內容結構的 API 版本。請使用 `\"1.0\"`。 |\n\n * 成功的回應（`200 OK`）\n回傳包含任務識別碼的 JSON 物件。\n\n**回應內容 Schema：**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"\"\n }\n}\n```\n\n**回應範例：**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe\"\n }\n}\n```\n\n * 錯誤回應（`400 Bad Request`、`401 InvalidApiKey` 等）\n會回傳標準的錯誤物件，並附帶描述失敗原因的訊息。\n\n**錯誤回應範例：**\n```json\n{\n \"status\": 400,\n \"error\": \"The operation could not be completed\",\n \"error_code\": \"CreditInsufficiency\"\n}\n```\n\n---\n\n* 3. 取得任務狀態與結果\n\n`GET /s2s/v2.0/task/makeup-vto/`\n\n取得進行中或已完成任務的目前狀態與結果。\n\n * 請求標頭\n\n| 標頭 | 值 |\n|--------|-------|\n| Authorization | `Bearer YOUR_API_KEY` |\n\n * 路徑參數\n\n| 參數 | 類型 | 說明 |\n|-----------|------|---------|\n| task_id | string | 從啟動任務端點回傳的識別碼。 |\n\n * 成功的回應（`200 OK`）\n包含狀態的 JSON 物件，若已完成則包含結果。\n\n**回應內容 Schema：**\n```json\n{\n \"data\": {\n \"task_status\": \"\", // 'success', 'error', or a processing state (e.g., 'queued', 'processing')\n \"results\": [ // 僅在 task_status 為 'success' 時出現\n {\n \"download_url\": \"\" // 下載處理後影像的 URL\n }\n ],\n \"failure_reason\": \"\" // 僅在 task_status 為 'error' 時出現\n }\n}\n```\n\n**成功回應範例：**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"success\",\n \"results\": {\n \"url\": \"https://s3.storage.prod/processed/image_123.jpg?token=...\"\n }\n }\n}\n```\n\n**引擎錯誤回應範例：**\nAPI 查詢已成功送出；然而，執行 AI 任務時發生錯誤。\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"error\",\n \"error\": \"exceed_max_filesize\",\n \"error_message\": \"string\",\n }\n}\n```\n > 請注意，若發生錯誤，無論是查詢錯誤或引擎錯誤，都不會消耗點數。\n\n**進行中回應範例：**\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"running\"\n }\n}\n```\n\n * 錯誤回應\n* `404 InvalidTaskId`：`task_id` 不存在或無效。\n* `401 InvalidApiKey`：API key 無效或缺失。\n* `500 TaskTimeout`：任務已成功完成或失敗，且已超過保留期限。\n\n**查詢錯誤回應範例：**\n```json\n{\n \"status\": 401,\n \"error_code\": \"InvalidApiKey\"\n}\n```\n > 請注意，若發生錯誤，無論是查詢錯誤或引擎錯誤，都不會消耗點數。\n\n---\n\n## 輸入與輸出\n* 彩妝特效 Schema\n\n本節定義 AI 彩妝任務請求內容的完整結構與限制。每個特效都是上層 `effects` 陣列中的一個物件。\n\n* 特效容器（上層）\n\n```json\n{\n \"version\": \"1.0\",\n \"effects\": [] // array — Contains makeup effect objects\n}\n```\n\n* 彩妝特效類別\n\n * `skin_smooth`\n```json\n{\n \"category\": \"skin_smooth\", // string, const \"skin_smooth\"\n \"skinSmoothStrength\": 50, // integer, range: 0..100\n \"skinSmoothColorIntensity\": 50 // integer, range: 0..100\n}\n```\n > **注意！** 若請求中未包含 ``skin_smooth`` 特效，AI 彩妝引擎會自動套用預設的 Skin Smooth 值 50。\n 若您希望套用彩妝但不進行肌膚平滑，請將所有 ``skinSmoothStrength`` 與 ``skinSmoothColorIntensity`` 參數設為 0。不過，為了獲得最佳結果與最高品質的融合，建議保留預設啟用的肌膚平滑。\n\n * `blush`\n```json\n{\n \"category\": \"blush\", // string, const \"blush\"\n \"pattern\": { // object\n \"name\": \"\" // string — 必須等於 blush.json 中的 `label`\n },\n \"palettes\": [ // array, minItems: (see colorNum in pattern)\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"satin\",\"shimmer\"]\n \"glowStrength\": 50, // integer, range: 0..100 — REQUIRED if texture=\"satin\"\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n \"shimmerDensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/blush.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"1 color\",\n \"label\": \"1color1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/483/a53cd4f4-43b6-4e19-b85a-ec7a95c6a47f.jpg\",\n \"tags\": [\n { \"id\": 100, \"name\": \"Blush 3D\" },\n { \"id\": 103, \"name\": \"Oblong\" }\n ],\n \"colorNum\": 1\n },\n {\n \"category\": \"2 colors\",\n \"label\": \"2colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/147/a8d86a4b-8aa0-48d7-a716-63ec78dfb30b.jpg\",\n \"tags\": [\n { \"id\": 100, \"name\": \"Blush 3D\" }\n ],\n \"colorNum\": 2\n },\n {\n \"category\": \"3 colors\",\n \"label\": \"3colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/af8b625b-ae3a-4211-9413-f22c16a5f174.jpg\",\n \"tags\": [\n { \"id\": 100, \"name\": \"Blush 3D\" },\n { \"id\": 104, \"name\": \"Round\" }\n ],\n \"colorNum\": 3\n }\n]\n```\n\n\n * `bronzer`\n```json\n{\n \"category\": \"bronzer\", // string, const \"bronzer\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 bronzer.json 中的 `label`\n \"palettes\": [\n { \"color\": \"#ff0000\", \"colorIntensity\": 50 } // hex color, int range: 0..100\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/bronzer.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"Bronzer\",\n \"label\": \"Bronzer1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/973/22ff2c07-d584-4ae6-8281-c095cd121a52.jpg\",\n \"tags\": [],\n \"colorNum\": 1\n }\n]\n```\n\n * `concealer`\n```json\n{\n \"category\": \"concealer\", // string, const \"concealer\"\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"colorIntensity\": 50, // integer, range: 0..100\n \"colorUnderEyeIntensity\": 50, // integer, range: 0..100\n \"coverageLevel\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n * `contour`\n```json\n{\n \"category\": \"contour\", // string, const \"contour\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 contour.json 中的 `label`\n \"palettes\": [\n { \"color\": \"#ff0000\", \"colorIntensity\": 50 } // hex color, int range: 0..100\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/contour.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"Heart face\",\n \"label\": \"HeartFace2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/731/49a1b3b9-b393-4bf4-b486-1493fe468436.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Invtriangle\",\n \"label\": \"Invtriangle1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/858/a94c8cca-5f8c-4b8b-a02d-94edb6a4ad7f.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Oval face\",\n \"label\": \"OvalFace6\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/906/644368a3-7eee-4ad9-829e-e2b3d4320fec.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Round face\",\n \"label\": \"RoundFace4\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/106/3e455b5f-7e2d-46f7-8627-dc137051c144.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Triangle face\",\n \"label\": \"TriangleFace2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/528/18765180-c254-4411-a25c-c1d78f5c3d77.jpg\",\n \"tags\": []\n }\n]\n```\n\n * `eyebrows`\n```json\n{\n \"category\": \"eyebrows\", // string, const \"eyebrows\"\n \"pattern\": {\n \"type\": \"shape\", // string, enum [\"shape\",\"color\"], default: \"shape\"\n \"name\": \"\", // string，type=\"shape\" 時必要 — eyebrows.json 的 label\n \"curvature\": 0, // integer, range: -100..100 (shape only)\n \"thickness\": 0, // integer, range: -100..100 (shape only)\n \"definition\": 0 // integer, range: 0..100 (shape only)\n },\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"colorIntensity\": 50, // integer, range: 0..100\n \"texture\": \"matte\", // string, enum [\"matte\",\"shimmer\"]\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture=\"shimmer\"\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n \"shimmerSize\": 50, // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n \"shimmerDensity\": 50 // integer, range: 0..100 — REQUIRED if texture=\"shimmer\"\n }\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyebrows.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"Arrow\",\n \"label\": \"Arrow1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/490/1fb96bf9-979e-4327-a8c4-8c503f541f1a.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Curved\",\n \"label\": \"Curved1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/389/1ccb300e-c7ed-4995-920e-7d1bf8da1fad.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Drama\",\n \"label\": \"Drama2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/196/5fb14bec-553d-4841-bba7-ca7e5e27c12e.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"High Arch\",\n \"label\": \"HighArch1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/609/7a8676dc-6f6a-4b12-aab0-c50328e448c5.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Original\",\n \"label\": \"Original2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/300/123551e9-ca94-4732-89ed-5b3866678555.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Soft Arch\",\n \"label\": \"SoftArch1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/121/2552ebf0-2705-43f7-b295-4fac21e18009.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Straight\",\n \"label\": \"Straight1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/1/7734e777-8e51-41f1-abaf-205f0ed5e3b4.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Thin\",\n \"label\": \"Thin1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/734/6ee10843-a251-4aa0-9183-db7f981d714d.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Upward\",\n \"label\": \"Upward4\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/751/76578317-f475-49c7-bd96-910ccad617ef.jpg\",\n \"tags\": []\n }\n]\n```\n\n * `eye_liner`\n```json\n{\n \"category\": \"eye_liner\", // string, const \"eye_liner\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 eyeliner.json 中的 label\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"metallicIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeliner.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"2 colors\",\n \"label\": \"2colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/419/71d9429a-dc08-4e80-9c46-6e55631ef766.jpg\",\n \"tags\": [\n {\n \"id\": 28,\n \"name\": \"Drama\"\n }\n ],\n \"colorNum\": 2\n },\n {\n \"category\": \"3 colors\",\n \"label\": \"3colors2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/208/056aa6cd-8678-470c-b111-b7653d7ddf93.jpg\",\n \"tags\": [\n {\n \"id\": 28,\n \"name\": \"Drama\"\n }\n ],\n \"colorNum\": 3\n },\n {\n \"category\": \"1 color\",\n \"label\": \"Arabic3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/726/1919aad4-21a2-493a-a5f8-48bc99a61ba5.jpg\",\n \"tags\": [\n {\n \"id\": 26,\n \"name\": \"Arabic\"\n }\n ],\n \"colorNum\": 1\n }\n]\n```\n\n * `eye_shadow`\n```json\n{\n \"category\": \"eye_shadow\", // string, const \"eye_shadow\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 eyeshadow.json 中的 label\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"shimmer\",\"metallic\"]\n \"shimmerColor\": \"#fc288f\", // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"shimmer\",\"metallic\"]\n \"metallicIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture=\"metallic\"\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ] // minItems: (see colorNum in pattern)\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyeshadow.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"1 color\",\n \"label\": \"1color1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/188/0322c4f9-e54d-4a6b-8072-6bb76560121a.jpg\",\n \"tags\": [\n {\n \"id\": 12,\n \"name\": \"Artistic\"\n },\n {\n \"id\": 14,\n \"name\": \"Dream\"\n },\n {\n \"id\": 15,\n \"name\": \"Trend\"\n }\n ],\n \"colorNum\": 1\n },\n {\n \"category\": \"2 colors\",\n \"label\": \"2colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/938/3348211c-1b83-4ab2-9c6a-ce06e4aa3528.jpg\",\n \"tags\": [\n {\n \"id\": 1,\n \"name\": \"Fan shape\"\n },\n {\n \"id\": 8,\n \"name\": \"Only upper lid\"\n }\n ],\n \"colorNum\": 2\n },\n {\n \"category\": \"3 colors\",\n \"label\": \"3colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/542/55e1b0fd-b888-47ff-bd3a-3dc1af2a7b69.jpg\",\n \"tags\": [\n {\n \"id\": 1,\n \"name\": \"Fan shape\"\n },\n {\n \"id\": 8,\n \"name\": \"Only upper lid\"\n }\n ],\n \"colorNum\": 3\n },\n {\n \"category\": \"4 colors\",\n \"label\": \"4colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/429/29cd5839-464b-4a7a-a5c1-c7b40e9464d7.jpg\",\n \"tags\": [\n {\n \"id\": 4,\n \"name\": \"Closed banana\"\n },\n {\n \"id\": 10,\n \"name\": \"Whole eye\"\n }\n ],\n \"colorNum\": 4\n },\n {\n \"category\": \"5 colors\",\n \"label\": \"5colors1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/2/824dcf7c-1273-4a30-8f1f-2137926057d6.jpg\",\n \"tags\": [\n {\n \"id\": 4,\n \"name\": \"Closed banana\"\n },\n {\n \"id\": 10,\n \"name\": \"Whole eye\"\n }\n ],\n \"colorNum\": 5\n }\n]\n```\n\n * `eyelashes`\n```json\n{\n \"category\": \"eyelashes\", // string, const \"eyelashes\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 eyelashes.json 中的 label\n \"palettes\": [\n { \"color\": \"#ff0000\", \"colorIntensity\": 50 } // hex color, int range: 0..100\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/eyelashes.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"Artistic\",\n \"label\": \"Artistic1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/146/7a8ed606-1c27-4d91-9320-c40a904f621f.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Natural\",\n \"label\": \"Natural1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/287/cd5cae75-a1b3-48f8-8537-e6e259213901.png\",\n \"tags\": []\n },\n {\n \"category\": \"Upper&Lower\",\n \"label\": \"Upper&Lower1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/18/2689ea2d-725e-4fa0-8563-df874ae1a83f.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Upper\",\n \"label\": \"Upper1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/982/c99bf74e-545f-4da7-a314-f3bd84b82156.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"UpperDense\",\n \"label\": \"UpperDense1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/888/452ec863-f0a8-40e7-aa33-31c0c39f57e2.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Winged\",\n \"label\": \"Winged1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/825/36ab3859-eae5-49e4-9d97-161698bbb8bb.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Wispies\",\n \"label\": \"Wispies1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/722/a2a727f6-748c-41e7-8ac0-c9c57c18c05a.png\",\n \"tags\": []\n }\n]\n```\n\n * `foundation`\n```json\n{\n \"category\": \"foundation\", // string, const \"foundation\"\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"colorIntensity\": 50, // integer, range: 0..100\n \"glowIntensity\": 50, // integer, range: 0..100\n \"coverageIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n * `highlighter`\n```json\n{\n \"category\": \"highlighter\", // string, const \"highlighter\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 highlighter.json 中的 label\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"glowIntensity\": 50, // integer, range: 0..100\n \"shimmerIntensity\": 50, // integer, range: 0..100\n \"shimmerDensity\": 50, // integer, range: 0..100\n \"shimmerSize\": 50, // integer, range: 0..100\n \"colorIntensity\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/highlighter.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"Heart face\",\n \"label\": \"HeartFace4\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/246/6ca40279-79cc-4918-b48a-64306009b365.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Invtriangle\",\n \"label\": \"Invtriangle2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/7/6b0b9760-612c-4319-bd81-855d262d8e89.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Oblong\",\n \"label\": \"Oblong11\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/862/b7279f4e-edf2-43f3-8156-561fe5a52ec3.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Oval face\",\n \"label\": \"OvalFace2\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/369/91097a05-9fd2-43cb-82e9-dd45e72b613b.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Round face\",\n \"label\": \"RoundFace3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/520/2d3ccbe2-36c3-43df-9e78-4c2c931fa431.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Square face\",\n \"label\": \"SquareFace3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/989/2959777b-19ca-4f4a-a023-3c8927191497.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Triangle face\",\n \"label\": \"TriangleFace3\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/customer/guest/SkuCustomImage/765/221c1f12-c621-4567-a8ee-1433038ee8a2.jpg\",\n \"tags\": []\n }\n]\n```\n\n * `lip_color`\n```json\n{\n \"category\": \"lip_color\", // string, const \"lip_color\"\n \"shape\": { // object — driven by lipshape.json\n \"name\": \"original\" // string — 必須等於 lipshape.json 中的 `label`\n },\n \"morphology\": { // optional object\n \"fullness\": 50, // integer, range: 0..100 (default: 0)\n \"wrinkless\": 50 // integer, range: 0..100 (default: 0)\n },\n \"palettes\": [ // minItems depends on style; often ≥1\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"gloss\",\"holographic\",\"metallic\",\"satin\",\"sheer\",\"shimmer\"]\n \"colorIntensity\": 50, // integer, range: 0..100\n \"gloss\": 50, // int, range: 0..100 — REQUIRED if texture in [\"gloss\",\"holographic\",\"metallic\",\"sheer\",\"shimmer\"]\n \"shimmerColor\": \"#ff0000\", // string, hex color \"#RRGGBB\" — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"shimmerIntensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"shimmerDensity\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"shimmerSize\": 50, // integer, range: 0..100 — REQUIRED if texture in [\"holographic\",\"metallic\",\"shimmer\"]\n \"transparencyIntensity\": 50 // integer, range: 0..100 — REQUIRED if texture in [\"gloss\",\"sheer\",\"shimmer\"]\n }\n ],\n \"style\": {\n \"type\": \"full\", // string, enum [\"full\",\"ombre\",\"twoTone\"]\n \"innerRatio\": 50, // int, range: 0..100 — REQUIRED if type=\"ombre\"\n \"featherStrength\": 50 // int, range: 0..100 — REQUIRED if type=\"ombre\"\n }\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/shapes/lipshape.json\n\n**各彩妝圖樣類別：**\n```json\n[{\n \"category\": \"general\",\n \"label\": \"original\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/original.png\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"heart-shaped\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/heart-shaped.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"m-shaped\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/m-shaped.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"petal\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/petal.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"plump\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/plump.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"pouty\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/pouty.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"smile\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/smile.jpg\",\n \"tags\": [\n ]\n }, {\n \"category\": \"general\",\n \"label\": \"vintage\",\n \"thumbnail\": \"https://plugins-media.makeupar.com/wcm-saas/images/lipshapes/vintage.jpg\",\n \"tags\": [\n ]\n }\n]\n```\n\n * `lip_liner`\n```json\n{\n \"category\": \"lip_liner\", // string, const \"lip_liner\"\n \"pattern\": { \"name\": \"\" }, // object — name 必須等於 lipliner.json 中的 label\n \"palettes\": [\n {\n \"color\": \"#ff0000\", // string, hex color \"#RRGGBB\"\n \"texture\": \"matte\", // string, enum [\"matte\",\"satin\"]\n \"colorIntensity\": 50, // integer, range: 0..100\n \"thickness\": 50, // integer, range: 0..100\n \"smoothness\": 50 // integer, range: 0..100\n }\n ]\n}\n```\n\n**完整圖樣目錄：**\nhttps://plugins-media.makeupar.com/wcm-saas/patterns/lipliner.json\n\n**各彩妝圖樣類別：**\n```json\n[\n {\n \"category\": \"Large & Full\",\n \"label\": \"Large&Full1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/417/7ac66cb2-2c7b-451c-8284-cc77791b7001.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Larger Lower\",\n \"label\": \"LargerLower1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/878/84b2ef48-3af4-4851-86d2-b01d10db82b2.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Larger Upper\",\n \"label\": \"LargerUpper1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/674f9f4c-7961-462e-8cc9-9a8acaad4168.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Natural\",\n \"label\": \"Natural1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/258/7533c08a-cc9c-45ab-9294-5d5a8114037d.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Rosebud\",\n \"label\": \"Rosebud1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/47/eb95e91f-6ef1-41f7-bc4f-aecd7d780c42.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Small\",\n \"label\": \"Small1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/396/6b78e461-24a6-4c6d-afb4-88beb71f1732.jpg\",\n \"tags\": []\n },\n {\n \"category\": \"Wider\",\n \"label\": \"Wider1\",\n \"thumbnail\": \"https://app-cdn-01.makeupar.com/console/SkuCustomImage/guest/867/21f92b70-72b5-4a57-b4d7-81c5cce757a6.jpg\",\n \"tags\": []\n }\n]\n```\n\n---\n\n## 內容範例\n\n以下是一個套用多個特效的有效 `effectJson` 內容完整範例。\n\n```json\n{\n \"version\": \"1.0\",\n \"effects\": [\n {\n \"category\": \"skin_smooth\",\n \"skinSmoothStrength\": 55,\n \"skinSmoothColorIntensity\": 45\n },\n {\n \"category\": \"blush\",\n \"pattern\": { \"name\": \"2colors1\" },\n \"palettes\": [\n {\n \"color\": \"#e19f9f\",\n \"texture\": \"matte\",\n \"colorIntensity\": 60,\n \"shimmerColor\": \"#d63252\",\n \"shimmerDensity\": 50\n },\n {\n \"color\": \"#c98a8a\",\n \"texture\": \"satin\",\n \"glowStrength\": 40,\n \"colorIntensity\": 70\n }\n ]\n },\n {\n \"category\": \"lip_color\",\n \"shape\": { \"name\": \"plump\" },\n \"morphology\": { \"fullness\": 30, \"wrinkless\": 25 },\n \"style\": { \"type\": \"full\" },\n \"palettes\": [\n {\n \"color\": \"#e11c43\",\n \"texture\": \"gloss\",\n \"colorIntensity\": 80,\n \"gloss\": 75\n }\n ]\n }\n ]\n}\n```\n在此範例中，`blush` 使用來自 `blush.json` 的 `2colors1` 圖樣，需要恰好兩個調色盤。`lip_color` 特效使用來自 `lipshape.json` 的 `plump` 形狀。\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n|AI 虛擬試妝|長邊 < 1920，臉寬 >= 100|< 10MB|jpg/jpeg/png|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n| ---- | ---- |\n|error_below_min_image_size|來源圖片尺寸小於最小值（期望：寬 >= 100px，高 >= 100px）\n|error_exceed_max_image_size|來源圖片尺寸大於最大值（期望：寬 < 1920px，高 < 1080px）\n|error_face_position_invalid |請確保您的整張臉在圖片中完全可見|\n|error_face_position_too_small|偵測到的臉部過小。請靠近鏡頭|\n|error_face_position_out_of_boundary|臉部過大或部分在畫面之外。請調整您的位置|\n|error_face_angle_invalid|臉部角度不正確。正面照片請將頭部保持在 10° 內。側面照片請確保超過 15°。|\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58（現代 TLS/HTTP 支援）
- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- 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" } ], "paths": { "/s2s/v2.0/task/makeup-vto": { "post": { "summary": "執行 AI 虛擬試妝任務。", "description": "這個端點啟動彩妝虛擬試妝流程。您必須提供來源檔案（透過網址或檔案 ID），並使用定義的特效 schema 指定要套用的特效。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。\n", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2" }, { "type": "object", "required": [ "effects" ], "properties": { "version": { "type": "string", "description": "彩妝特效規範的版本。除非另有指定，預設為 `\"1.0\"`。\n", "default": "1.0", "example": "1.0" }, "effects": { "type": "array", "description": "要套用的彩妝特效陣列。每個特效物件都必須指定 `category`，並符合該彩妝類型的 schema。\n", "items": { "anyOf": [ { "$ref": "#/components/schemas/SkinSmoothEffect" }, { "$ref": "#/components/schemas/BlushEffect" }, { "$ref": "#/components/schemas/BronzerEffect" }, { "$ref": "#/components/schemas/ConcealerEffect" }, { "$ref": "#/components/schemas/ContourEffect" }, { "$ref": "#/components/schemas/EyebrowsEffect" }, { "$ref": "#/components/schemas/EyelinerEffect" }, { "$ref": "#/components/schemas/EyeshadowEffect" }, { "$ref": "#/components/schemas/EyelashesEffect" }, { "$ref": "#/components/schemas/FoundationEffect" }, { "$ref": "#/components/schemas/HighlighterEffect" }, { "$ref": "#/components/schemas/LipColorEffect" }, { "$ref": "#/components/schemas/LipLinerEffect" } ] } } } } ] } } } }, "responses": { "200": { "description": "任務執行成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "description": "任務執行失敗", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/responses/RunError" } ] } } } }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/makeup-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": { "EngineErrorCode": { "type": "string", "nullable": true, "enum": [ "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_decode_image", "error_nsfw_content_detected", "error_inference", "unknown_internal_error" ], "description": "錯誤：\n\n- `exceed_max_filesize` - 輸入檔案大小超過上限\n\n- `invalid_parameter` - 參數值無效\n\n- `error_download_image` - 下載來源圖片錯誤\n\n- `error_decode_image` - 解碼來源圖片錯誤\n\n- `unknown_internal_error` - 其他\n" }, "FileV1.1": { "title": "File V1.1", "description": "這個物件代表一個檔案。", "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "content_type", "file_name", "file_size" ], "properties": { "content_type": { "type": "string", "example": "image/jpg", "description": "這個檔案的內容 MIME 類型。目前可用的值列於 enum 中。" }, "file_name": { "type": "string", "example": "my-selfie.jpg", "description": "這個檔案的名稱" }, "file_size": { "type": "integer", "example": 50000, "description": "這個檔案的內容長度，以位元組計。不應超過 10MB。" } } } } } }, "BasicFileResponse": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "content_type": { "type": "string", "example": "image/jpg", "description": "這個檔案的內容 MIME 類型。" }, "file_name": { "type": "string", "example": "my-selfie.jpg", "description": "這個檔案的名稱" }, "file_id": { "type": "string", "example": "U8aqJbsXGT537jtGnEDFHqxdDXqh8+oTF/cSkLimzuvVwMP+Jb1XbjPsf7ZgUgLY", "description": "這個檔案的 ID。其他執行任務的 API 會需要這個 `file_id`。" }, "requests": { "type": "array", "description": "使用下方的 `url`、`headers`、`method` 上傳檔案。完成後，使用 `file_id` 繼續呼叫執行任務的 API。", "items": { "type": "object", "properties": { "headers": { "type": "object", "example": { "Content-Type": "image/jpg", "Content-Length": 50000 }, "description": "上傳檔案時要納入的標頭" }, "url": { "type": "string", "example": "https://example.com/presigned-upload-url", "description": "上傳這個檔案的網址" }, "method": { "type": "string", "example": "PUT", "description": "上傳這個檔案所用的 HTTP 方法" } } } } } } } } }, "FileResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "description": "回應狀態" }, "data": { "$ref": "#/components/schemas/BasicFileResponse" } } }, "BasicRunTaskV2SrcFileUrl": { "title": "以來源檔案網址執行任務", "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "要執行任務的檔案網址。該網址應可公開存取。", "example": "https://example.com/selfie.jpg" } } }, "BasicRunTaskV2SrcFileId": { "title": "以來源檔案 ID 執行任務", "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "要執行任務的檔案 ID。檔案 ID 來自上傳檔案 API。", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2": { "title": "BasicRunTaskV2", "anyOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl" }, { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" } ] }, "BasicRunTaskResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "回應狀態", "example": 200 }, "data": { "type": "object", "properties": { "task_id": { "type": "string", "description": "這個任務的 ID。任務結果可以此 ID 查詢，有效期限 30 天。", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } } } }, "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": { "$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2" } } } } }, "SkinSmoothEffect": { "type": "object", "description": "控制套用到肌膚的 AI 生成平滑效果。若未提供 skin_smooth 特效，系統會自動套用強度 50 的平滑效果，以達到真實的融合。\n", "required": [ "category" ], "properties": { "category": { "type": "string", "enum": [ "skin_smooth" ], "description": "將此特效識別為肌膚平滑特效。必須始終為 \"skin_smooth\"。\n" }, "skinSmoothStrength": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50, "description": "套用到整體肌膚質地的平滑強度。較高的值會帶來更柔軟、更像噴槍修飾的肌膚外觀。\n" }, "skinSmoothColorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "default": 50, "description": "平滑過程中套用的色彩混合強度。有助於統一膚色並減少色彩不一致。\n" } }, "example": { "category": "skin_smooth", "skinSmoothStrength": 50, "skinSmoothColorIntensity": 50 } }, "BlushEffect": { "type": "object", "description": "使用預先定義的圖樣與可自訂的調色盤，將腮紅套用到臉頰。圖樣名稱必須對應官方 blush.json 圖樣目錄中的 labels。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "blush" ], "description": "將此特效識別為腮紅特效。必須始終為 \"blush\"。\n" }, "pattern": { "type": "object", "description": "定義腮紅在臉上的位置。每個圖樣對應 blush.json 中的一種臉型與佈局。\n", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "腮紅圖樣的名稱。必須等於 blush.json 圖樣目錄中的某個 `label`。\n", "example": "1color1" } } }, "palettes": { "type": "array", "minItems": 1, "description": "調色盤條目的清單。所需調色盤的數量取決於所選腮紅圖樣中定義的 `colorNum` 欄位。\n", "items": { "type": "object", "required": [ "color", "texture", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 hex 格式（#RRGGBB）表示的主要腮紅顏色。作為腮紅的主導色素。\n", "pattern": "^#?[0-9A-Fa-f]{6}$" }, "texture": { "type": "string", "enum": [ "matte", "satin", "shimmer" ], "description": "腮紅的質地：\n - matte：純色素，無光澤\n - satin：柔和光暈，需要 glowStrength\n - shimmer：閃亮或發光，需要 shimmer 參數\n" }, "glowStrength": { "type": "integer", "minimum": 0, "maximum": 100, "description": "satin 腮紅質地的光暈強度。texture = \"satin\" 或 \"shimmer\" 時必要。\n" }, "shimmerColor": { "type": "string", "description": "閃亮顆粒的顏色。texture = \"shimmer\" 時必要。\n" }, "shimmerDensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "腮紅中閃亮顆粒的密度。texture = \"shimmer\" 時必要。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "相對於基礎色素的腮紅顏色強度。\n" } } } } }, "example": { "category": "blush", "pattern": { "name": "1color1" }, "palettes": [ { "color": "#ff7777", "texture": "matte", "colorIntensity": 60 } ] } }, "BronzerEffect": { "type": "object", "description": "套用古銅粉以增添膚色溫暖感與日曬輪廓。圖樣名稱必須對應 bronzer.json 的條目。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "bronzer" ], "description": "將此特效識別為古銅粉特效。必須始終為 \"bronzer\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "定義古銅粉的套用佈局。圖樣名稱必須對應 bronzer.json 中的某個 `label`。\n", "properties": { "name": { "type": "string", "example": "Bronzer1", "description": "來自 bronzer.json 目錄的古銅粉圖樣名稱。\n" } } }, "palettes": { "type": "array", "description": "古銅粉調色盤包含色素顏色與強度控制。\n", "items": { "type": "object", "required": [ "color", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 hex 格式（#RRGGBB）表示的古銅粉顏色。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "古銅粉色素的強度。" } } } } }, "example": { "category": "bronzer", "pattern": { "name": "Bronzer1" }, "palettes": [ { "color": "#c08050", "colorIntensity": 50 } ] } }, "ConcealerEffect": { "type": "object", "description": "加入遮瑕產品，用於中和瑕疵、均勻膚色，並提亮眼下區域。遮瑕不使用圖樣——僅有色素與強度控制。所有調色盤欄位都是必要的，以確保在各臉部區域的行為一致。\n", "required": [ "category", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "concealer" ], "description": "將此特效識別為遮瑕特效。必須始終為 \"concealer\"。\n" }, "palettes": { "type": "array", "minItems": 1, "description": "一個或多個遮瑕調色盤，定義顏色與強度屬性。同一個調色盤會套用到相關的臉部區域，例如眼下、額頭與下巴的修飾區域。\n", "items": { "type": "object", "required": [ "color", "colorIntensity", "colorUnderEyeIntensity", "coverageLevel" ], "properties": { "color": { "type": "string", "description": "以 hex RGB 格式（#RRGGBB）表示的遮瑕色號。通常應與膚色相符或略微提亮。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "套用於整張臉的遮瑕色素強度。\n" }, "colorUnderEyeIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "針對眼下區域的特定色素控制。有助於提亮黑眼圈，而不會在其他區域過度應用。\n" }, "coverageLevel": { "type": "integer", "minimum": 0, "maximum": 100, "description": "決定遮瑕覆蓋的不透明度。較高的值可隱藏更多色差或瑕疵。\n" } } } } }, "example": { "category": "concealer", "palettes": [ { "color": "#e6c7a8", "colorIntensity": 50, "colorUnderEyeIntensity": 50, "coverageLevel": 60 } ] } }, "ContourEffect": { "type": "object", "description": "使用針對特定臉型設計的圖樣，定義用於臉部雕塑的修容。修容圖樣決定高光/陰影的位置，調色盤則控制修容色號。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "contour" ], "description": "將此特效識別為修容特效。必須始終為 \"contour\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "定義修容陰影套用在臉上的位置。必須使用 contour.json 中定義的圖樣名稱（例如 HeartFace2、OvalFace6）。\n", "properties": { "name": { "type": "string", "description": "修容圖樣的名稱。必須等於 contour.json 中的某個 `label`。\n", "example": "OvalFace6" } } }, "palettes": { "type": "array", "minItems": 1, "description": "定義修容所用的色素。通常為比粉底更深的冷色調或中性色號。\n", "items": { "type": "object", "required": [ "color", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 #RRGGBB hex 格式表示的修容色素顏色。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "修容色素的強度。較高的值會產生更深的陰影。\n" } } } } }, "example": { "category": "contour", "pattern": { "name": "OvalFace6" }, "palettes": [ { "color": "#8a5b3e", "colorIntensity": 55 } ] } }, "EyebrowsEffect": { "type": "object", "description": "使用可自訂的幾何形狀與調色盤，為眉毛塑形並上色。當 `pattern.type = shape` 時，圖樣定義眉毛的幾何形狀（眉峰、弧度、粗細）。當 `pattern.type = color` 時，僅套用色素變化。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "eyebrows" ], "description": "將此特效識別為眉毛造型特效。必須始終為 \"eyebrows\"。\n" }, "pattern": { "type": "object", "description": "此設定定義眉毛圖樣模式，可以調整形狀，或僅套用顏色。需要時，圖樣名稱必須對應 eyebrows.json 中的 labels。\n", "required": [ "type" ], "oneOf": [ { "title": "ShapePattern", "description": "以形狀為基礎的眉毛造型（幾何形狀＋可選顏色）。", "required": [ "name" ], "properties": { "type": { "type": "string", "enum": [ "shape" ], "description": "使用自訂的眉毛圖樣形狀" }, "name": { "type": "string", "description": "眉毛形狀圖樣的名稱。必須對應 eyebrows.json 中的某個 `label`。\n", "example": "SoftArch1" }, "curvature": { "type": "integer", "minimum": -100, "maximum": 100, "description": "調整眉毛的彎曲程度。負值＝更平／更直，正值＝更彎。\n" }, "thickness": { "type": "integer", "minimum": -100, "maximum": 100, "description": "相對於偵測到的眉毛，控制眉毛粗細的調整。正值＝更粗，負值＝更細。\n" }, "definition": { "type": "integer", "minimum": 0, "maximum": 100, "description": "眉毛的清晰度與鮮明度。較高的值會增加眉緣的明確度，呈現更乾淨的外觀。\n" } } }, { "title": "ColorPattern", "description": "僅上色的眉毛造型（不改變幾何形狀）。", "properties": { "type": { "type": "string", "enum": [ "color" ], "description": "使用使用者原本的眉毛形狀" } } } ] }, "palettes": { "type": "array", "minItems": 1, "description": "眉毛調色盤。每個調色盤控制色素與可選的閃亮特效（僅適用於閃亮質地）。\n", "items": { "type": "object", "required": [ "color", "colorIntensity", "texture" ], "properties": { "color": { "type": "string", "description": "以 #RRGGBB 格式表示的眉毛色素顏色。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "套用眉毛顏色時使用的色素強度。\n" }, "texture": { "type": "string", "enum": [ "matte", "shimmer" ], "description": "眉毛色素的質地風格。Shimmer 會為眉毛加入反射光澤。\n" }, "shimmerColor": { "type": "string", "description": "texture = shimmer 時套用的閃亮顏色。\n" }, "shimmerIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮光暈的強度。僅在 texture = shimmer 時必要。\n" }, "shimmerSize": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮顆粒的大小。閃亮質地時必要。\n" }, "shimmerDensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "眉毛中閃亮顆粒的密度。閃亮質地時必要。\n" } } } } }, "example": { "category": "eyebrows", "pattern": { "type": "shape", "name": "SoftArch1", "curvature": 10, "thickness": 5, "definition": 50 }, "palettes": [ { "color": "#3b2f2f", "colorIntensity": 70, "texture": "matte" } ] } }, "EyelinerEffect": { "type": "object", "description": "使用可自訂的圖樣與色素設定套用眼線。圖樣定義眼線的佈局（例如阿拉伯式形狀、飛眼線風格），調色盤則指定顏色、質地、閃亮/金屬特效與強度。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "eye_liner" ], "description": "將此特效識別為眼線特效。必須始終為 \"eye_liner\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "定義眼線的形狀與位置。圖樣名稱必須對應 eyeliner.json 中的 labels。\n", "properties": { "name": { "type": "string", "description": "眼線圖樣的名稱。必須等於 eyeliner.json 中的某個 label。\n", "example": "Arabic3" } } }, "palettes": { "type": "array", "minItems": 1, "description": "眼線調色盤條目。每個調色盤控制色素顏色、閃亮/金屬特效與整體強度。當所選眼線圖樣需要多種顏色時，會使用多個調色盤。\n", "items": { "type": "object", "required": [ "color", "texture", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 #RRGGBB 格式表示的眼線色素顏色。\n" }, "texture": { "type": "string", "enum": [ "matte", "shimmer", "metallic" ], "description": "眼線的質地光澤說明了眼線的外觀：matte 為平坦的不透明效果；shimmer 為閃亮反射的質感（含 shimmer 欄位）；metallic 為亮面金屬光澤（需要 shimmer 欄位與 metallic 強度）。\n" }, "shimmerColor": { "type": "string", "description": "用於閃亮或金屬反射顆粒的顏色。texture 為 shimmer 或 metallic 時必要。\n" }, "shimmerIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "反射閃亮的強度。texture 為 shimmer 或 metallic 時必要。\n" }, "metallicIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "金屬反射程度。texture = metallic 時必要。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "眼線顏色的色素強度。\n" } } } } }, "example": { "category": "eye_liner", "pattern": { "name": "Arabic3" }, "palettes": [ { "color": "#000000", "texture": "matte", "colorIntensity": 80 } ] } }, "EyeshadowEffect": { "type": "object", "description": "使用可自訂的多色調色盤與質地套用眼影。眼影圖樣定義佈局（例如 1 到 5 色），調色盤則指定色素與閃亮/金屬屬性。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "eye_shadow" ], "description": "將此特效識別為眼影特效。必須始終為 \"eye_shadow\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "定義眼影的位置圖樣。必須對應 eyeshadow.json 中的 `label`（例如 1color1、2colors1 等）。\n", "properties": { "name": { "type": "string", "description": "來自 eyeshadow.json 的圖樣名稱，決定顏色數量與眼影位置區域。\n", "example": "2colors1" } } }, "palettes": { "type": "array", "minItems": 1, "description": "一個或多個色素調色盤條目。所需調色盤的數量取決於圖樣的 `colorNum`。每個調色盤定義眼影圖樣中的特定層級/顏色。\n", "items": { "type": "object", "required": [ "color", "texture", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 HEX 格式（#RRGGBB）表示的眼影色素顏色。\n" }, "texture": { "type": "string", "enum": [ "matte", "shimmer", "metallic" ], "description": "眼影的表面外觀決定質感：matte 為平滑平坦的外觀；shimmer 為閃亮效果（需要 shimmer 參數）；metallic 為大膽的金屬光澤（需要 shimmer 參數與 metallic 強度）。\n" }, "shimmerColor": { "type": "string", "description": "閃亮顆粒的顏色。texture = shimmer 或 metallic 時必要。\n" }, "shimmerIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "shimmer 或 metallic 質地的反射閃亮強度。\n" }, "metallicIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "金屬反射程度；metallic 質地時必要。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "每個眼影顏色的整體色素程度。\n" } } } } }, "example": { "category": "eye_shadow", "pattern": { "name": "2colors1" }, "palettes": [ { "color": "#b07baf", "texture": "shimmer", "shimmerColor": "#f2d3f5", "shimmerIntensity": 60, "colorIntensity": 70 }, { "color": "#8e5c9c", "texture": "matte", "colorIntensity": 65 } ] } }, "EyelashesEffect": { "type": "object", "description": "將色素套用到偵測到的睫毛上，以強化睫毛。睫毛延伸或密度增強取決於所選圖樣，調色盤則控制睫毛顏色與強度。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "eyelashes" ], "description": "將此特效識別為睫毛特效。必須始終為 \"eyelashes\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "定義套用哪種睫毛風格（自然、藝術、飛揚、上/下睫毛等）。必須對應 eyelashes.json 中的某個 `label`。\n", "properties": { "name": { "type": "string", "description": "來自 eyelashes.json 的睫毛圖樣名稱。\n", "example": "Upper1" } } }, "palettes": { "type": "array", "minItems": 1, "description": "睫毛調色盤。睫毛不支援閃亮/金屬特效——僅支援顏色與強度。\n", "items": { "type": "object", "required": [ "color", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 HEX 格式（#RRGGBB）表示的睫毛顏色。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "套用到睫毛的深色/色素強度。\n" } } } } }, "example": { "category": "eyelashes", "pattern": { "name": "Upper1" }, "palettes": [ { "color": "#000000", "colorIntensity": 80 } ] } }, "FoundationEffect": { "type": "object", "description": "使用色素、覆蓋與光暈控制套用粉底，以均勻膚色。與腮紅/修容不同，粉底沒有圖樣——它基於肌膚分割全域套用。\n", "required": [ "category", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "foundation" ], "description": "將此特效識別為粉底特效。必須始終為 \"foundation\"。\n" }, "palettes": { "type": "array", "minItems": 1, "description": "粉底調色盤條目，控制色調、覆蓋、光暈與色彩強度。\n", "items": { "type": "object", "required": [ "color", "colorIntensity", "glowIntensity", "coverageIntensity" ], "properties": { "color": { "type": "string", "description": "以 #RRGGBB 格式表示的粉底色號。通常接近自然膚色。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "粉底著色的強度。\n" }, "glowIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "為肌膚妝效加入光澤感。較高的值會產生光澤或水光效果。\n" }, "coverageIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "控制粉底覆蓋的不透明度。較高的值可隱藏更多瑕疵。\n" } } } } }, "example": { "category": "foundation", "palettes": [ { "color": "#eac595", "colorIntensity": 50, "glowIntensity": 10, "coverageIntensity": 50 } ] } }, "HighlighterEffect": { "type": "object", "description": "在臉部的高點（顴骨、丘比特弓、鼻樑等）加入反射高光。圖樣依據臉型決定高光位置。調色盤控制閃亮、光暈、密度、顆粒大小與色彩強度。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "highlighter" ], "description": "將此特效識別為高光特效。必須始終為 \"highlighter\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "高光位置圖樣。必須對應 highlighter.json 中的某個 `label`（例如 HeartFace4、Oblong11、OvalFace2）。\n", "properties": { "name": { "type": "string", "description": "來自 highlighter.json 目錄的高光圖樣名稱。\n", "example": "SquareFace3" } } }, "palettes": { "type": "array", "minItems": 1, "description": "高光調色盤條目，定義閃亮、光暈、密度與顏色。\n", "items": { "type": "object", "required": [ "color", "glowIntensity", "shimmerIntensity", "shimmerDensity", "shimmerSize", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 #RRGGBB HEX 格式表示的高光色素顏色。通常為白色、香檳色、金色或粉紅色調。\n" }, "glowIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "加入肌膚的非閃亮光暈量。較高的值會帶來更明亮、更有光澤的妝效。\n" }, "shimmerIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮反射的強度。較高的值＝更閃耀。\n" }, "shimmerDensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "每個區域的閃亮顆粒數量。較高的密度會創造更閃亮的效果。\n" }, "shimmerSize": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮顆粒的大小。較大的顆粒會創造類似亮粉的效果；較小＝細緻閃亮。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "高光顏色的色素強度。\n" } } } } }, "example": { "category": "highlighter", "pattern": { "name": "SquareFace3" }, "palettes": [ { "color": "#FFF7F8", "glowIntensity": 60, "shimmerIntensity": 50, "shimmerDensity": 40, "shimmerSize": 50, "colorIntensity": 50 } ] } }, "LipColorEffect": { "type": "object", "description": "以多種形狀、妝效與藝術風格套用唇膏。包含對唇部形態（飽滿度、紋路）、質地（matte、gloss、metallic、shimmer、sheer 等）、閃亮/光澤參數、多色圖樣，以及漸層/雙色風格的控制。\n", "required": [ "category", "shape", "palettes", "style" ], "properties": { "category": { "type": "string", "enum": [ "lip_color" ], "description": "將此特效識別為唇膏/唇色特效。必須始終為 \"lip_color\"。\n" }, "shape": { "type": "object", "description": "定義唇部邊界與形狀修改。圖樣名稱必須對應 lipshape.json（例如 plump、original、pouty）。\n", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "用於修改唇緣與輪廓的唇形風格。必須等於 lipshape.json 中的某個 `label`。\n", "example": "plump" } } }, "morphology": { "type": "object", "description": "對唇部的選填形態調整。可增強飽滿度並減少唇部紋路。\n", "properties": { "fullness": { "type": "integer", "default": 0, "minimum": 0, "maximum": 100, "description": "控制唇部看起來的飽滿程度。較高的值＝更大、更飽滿的嘴唇。\n" }, "wrinkless": { "type": "integer", "default": 0, "minimum": 0, "maximum": 100, "description": "平滑唇部的紋路與質地。較高的值會帶來更平滑的唇部外觀。\n" } } }, "palettes": { "type": "array", "minItems": 1, "description": "唇色调色盤條目，控制色素、質地、閃亮與光澤。漸層或雙色風格可使用多個調色盤。\n", "items": { "type": "object", "required": [ "color", "texture", "colorIntensity" ], "properties": { "color": { "type": "string", "description": "以 HEX 格式（#RRGGBB）表示的唇膏顏色。\n" }, "texture": { "type": "string", "enum": [ "matte", "gloss", "holographic", "metallic", "satin", "sheer", "shimmer" ], "description": "此設定說明唇部妝效的質地。若選擇 gloss，請務必納入 gloss 屬性。若為 shimmer、metallic 或 holographic 妝效，請加入 shimmer 相關欄位。若選擇 sheer、shimmer 或 gloss，別忘了納入透明度強度。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "唇膏色素的強度。\n" }, "gloss": { "type": "integer", "minimum": 0, "maximum": 100, "description": "gloss/holographic/metallic/sheer/shimmer 質地的光澤程度。\n" }, "shimmerColor": { "type": "string", "description": "shimmer、metallic 或 holographic 質地的閃亮顆粒顏色。\n" }, "shimmerIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮反射的強度。\n" }, "shimmerDensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮顆粒的密度。\n" }, "shimmerSize": { "type": "integer", "minimum": 0, "maximum": 100, "description": "閃亮顆粒的大小。\n" }, "transparencyIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "透明度效果強度。用於 sheer、shimmer 或 gloss 質地。\n" } } } }, "style": { "type": "object", "description": "風格描述唇色的藝術外觀，可以是均勻的完整色號、漸層混合色調的漸層風格，或是在唇部不同區域使用對比色的雙色效果。\n", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "full", "ombre", "twoTone" ], "description": "唇部著色的風格。\n" }, "innerColorRatio": { "type": "integer", "minimum": 0, "maximum": 100, "description": "決定次要顏色向內延伸的程度（僅適用於漸層）。type = ombre 時必要。\n" }, "blendStrength": { "type": "integer", "minimum": 0, "maximum": 100, "description": "顏色之間的混合柔和度。type = ombre 時必要。\n" } } } }, "example": { "category": "lip_color", "shape": { "name": "plump" }, "morphology": { "fullness": 20, "wrinkless": 10 }, "style": { "type": "full" }, "palettes": [ { "color": "#C2185B", "texture": "gloss", "colorIntensity": 80, "gloss": 70, "transparencyIntensity": 30 } ] } }, "LipLinerEffect": { "type": "object", "description": "沿唇緣套用最外層色素，以強化形狀明確度。適用於精修唇部邊界、調整對稱，以及支援漸層/雙色妝效。\n", "required": [ "category", "pattern", "palettes" ], "properties": { "category": { "type": "string", "enum": [ "lip_liner" ], "description": "將此特效識別為唇線特效。必須始終為 \"lip_liner\"。\n" }, "pattern": { "type": "object", "required": [ "name" ], "description": "依據 lipliner.json 的圖樣定義唇線位置。\n", "properties": { "name": { "type": "string", "description": "唇線圖樣的名稱（例如 Natural1、LargerUpper1）。\n", "example": "Natural1" } } }, "palettes": { "type": "array", "minItems": 1, "description": "唇線調色盤條目，定義顏色、粗細與平滑度。\n", "items": { "type": "object", "required": [ "color", "texture", "colorIntensity", "thickness", "smoothness" ], "properties": { "color": { "type": "string", "description": "以 HEX 格式表示的唇線色素顏色。\n" }, "texture": { "type": "string", "enum": [ "matte", "satin" ], "description": "唇線的妝效類型。\n" }, "colorIntensity": { "type": "integer", "minimum": 0, "maximum": 100, "description": "唇線色素的強度。\n" }, "thickness": { "type": "integer", "minimum": 0, "maximum": 100, "description": "唇線線條的粗細——較高的值會產生更明顯的輪廓。\n" }, "smoothness": { "type": "integer", "minimum": 0, "maximum": 100, "description": "線條邊緣的平滑度。較高的值會產生更柔和、融合感更強的線條。\n" } } } } }, "example": { "category": "lip_liner", "pattern": { "name": "Natural1" }, "palettes": [ { "color": "#A63A50", "texture": "matte", "colorIntensity": 70, "thickness": 40, "smoothness": 50 } ] } } }, "responses": { "InvalidParameters": { "description": "請求參數無效", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "回應狀態" }, "error": { "type": "string", "description": "錯誤訊息", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "InvalidParameters" ] } } } } } }, "InvalidApiKey": { "description": "API Key 無效、已停用或已到期", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "回應狀態" }, "error_code": { "type": "string", "enum": [ "InvalidApiKey", "InactiveApiKey", "ExpiredApiKey" ] } } } } } }, "TooManyRequests": { "description": "在指定時間內請求過多" }, "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": [ "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest", "InvalidParameters" ] } } }, "TaskTimeout": { "description": "任務在預期時間內沒有回應", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "回應狀態", "example": 500 }, "error_code": { "type": "string", "enum": [ "TaskTimeout" ] } } } } } }, "InvalidTaskId": { "description": "任務 id 無效", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "回應狀態", "example": 400 }, "error_code": { "type": "string", "enum": [ "InvalidTaskId" ] } } } } } } } } }