{ "openapi": "3.0.0", "info": { "title": "AI 完整妝容虛擬試妝", "description": "# 概述\nAI 完整妝容虛擬試妝 API 提供完整的工作流程，將專業設計的臉部造型套用到使用者照片。每個造型都由美妝專家打造，可透過 API 即刻套用。\n\n## 整合指南\n本指南將引導您完成：\n\n* **端點：** `/s2s/v2.0/task/look-vto`\n* **認證：** 所有請求都需要 `Authorization: Bearer `\n* **工作流程：**\n 1. **準備自拍：** 上傳圖片，或提供有效的圖片網址\n 1. **列出造型範本：** 列出可用的 AI 完整妝容範本\n 1. **啟動任務（`POST`）：** 提交您的圖片 id/網址與造型 ``template_id``。\n 1. **取得任務 ID：** 從回應中取得 `task_id`。\n 1. **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢，直到 `task_status` 為 `\"success\"` 或 `\"error\"`。\n\n---\n\n* API Playground\n\n使用我們的官方 playground 進行互動式探索與測試：\n\n**API Playground：**\n[http://yce.makeupar.com/api-console/en/api-playground/ai-look-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-look-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\n* 1. 上傳圖片\n\n您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。\n\n * 上傳端點\n\n```\nPOST /s2s/v2.0/file\n```\n\n或者，若您已有公開的圖片網址，可跳過此步驟。\n\n---\n\n* 2. 列出可用的造型風格\n\n取得所有可用於虛擬試妝的 AI 彩妝造型範本。\n\n * 端點\n\n```\nGET /s2s/v2.0/task/template/look-vto\n```\n\n * 查詢參數\n\n| 參數 | 說明 |\n| ---------------- | ------------------------------- |\n| `page_size` | 每頁的項目數量 |\n| `starting_token` | 用於分頁的令牌（選填） |\n\n * JavaScript 請求範例\n\n```javascript\nconst data = null;\n\nconst xhr = new XMLHttpRequest();\nxhr.withCredentials = true;\n\nxhr.addEventListener('readystatechange', function () {\n if (this.readyState === this.DONE) {\n console.log(this.responseText);\n }\n});\n\nxhr.open('GET', 'https://yce-api-01.makeupar.com/s2s/v2.0/task/template/look-vto?page_size=20&starting_token=73a3c9e69b89');\nxhr.setRequestHeader('Authorization', 'Bearer ');\n\nxhr.send(data);\n```\n\n * 成功回應範例\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"templates\": [\n {\n \"id\": \"good_template_001\",\n \"thumb\": \"縮略圖預覽圖片網址\",\n \"title\": \"Berry Smooth\",\n \"category_name\": \"Daily\"\n }\n ],\n \"next_token\": 73a3c9e69b89\n }\n}\n```\n\n> **注意：** 在建立造型 VTO 任務時，使用 `id` 值（`template_id`）。\n\n---\n\n* 3. 建立造型 VTO 任務並輪詢結果\n\n當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。\n\n * 建立任務端點\n\n```\nPOST /s2s/v2.0/task/look-vto\n```\n\n * 輪詢端點\n\n```\nGET /s2s/v2.0/task/look-vto/{task_id}\n```\n\n---\n\n * JavaScript 實作範例\n\n```javascript\nconst BASE_URL = 'https://yce-api-01.makeupar.com/s2s/v2.0/task/look-vto';\nconst START_METHOD = 'POST';\nconst HEADERS = {\n \"Content-Type\": \"application/json\",\n \"Authorization\": \"Bearer YOUR_API_KEY\"\n};\n\nconst sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));\n\nasync function startTask() {\n const init = {\n method: START_METHOD,\n headers: HEADERS,\n body: JSON.stringify({\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/sample_Image_7_fa28b2618a.jpg\",\n \"template_id\": \"all_rosy_chic\"\n })\n };\n\n const res = await fetch(BASE_URL, init);\n if (!res.ok) throw new Error(`Start request failed: ${res.status} ${res.statusText}`);\n\n const payload = await res.json().catch(() => ({}));\n const taskId = payload?.data?.task_id;\n if (!taskId) throw new Error('task_id missing: ' + JSON.stringify(payload));\n\n console.log('[startTask] Task started, id =', taskId);\n return taskId;\n}\n\nasync function pollTask(taskId, { intervalMs = 2000, maxAttempts = 300 } = {}) {\n for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n const pollUrl = `${BASE_URL}/${taskId}`;\n const res = await fetch(pollUrl, { method: 'GET', headers: HEADERS });\n\n if (!res.ok) throw new Error(`Polling failed: ${res.status} ${res.statusText}`);\n\n const payload = await res.json().catch(() => ({}));\n const status = payload?.data?.task_status;\n console.log(`[pollTask] Attempt ${attempt} status = ${status}`);\n\n if (status === 'success') {\n console.log('[pollTask] Success results:', payload?.data?.results);\n return payload;\n }\n\n if (status === 'error') {\n throw new Error('Task failed: ' + JSON.stringify(payload));\n }\n\n await sleep(intervalMs);\n }\n\n throw new Error('Polling timeout: Max attempts exceeded');\n}\n\n(async () => {\n try {\n const taskId = await startTask();\n const final = await pollTask(taskId);\n console.log('[main] Final response:', final);\n } catch (e) {\n console.error('[main] Flow error:', e);\n }\n})();\n```\n\n---\n\n * 成功回應範例\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/.../result.jpg?...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\n`results.url` 欄位包含最終渲染的虛擬彩妝影像。\n\n---\n\n* 摘要\n\n| 步驟 | 說明 |\n| -------------------------- | ---------------------------------------- |\n| **1. 上傳圖片** | 直接上傳，或提供圖片網址。 |\n| **2. 列出造型範本** | 取得可用的造型風格及其 ID。 |\n| **3. 建立 VTO 任務** | 提交圖片網址 + 範本 ID。 |\n| **4. 輪詢至完成** | 取得最終結果圖片網址。 |\n\n這個工作流程確保可靠、開發者友善的整合，用於即時虛擬彩妝試色體驗。\n\n---\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## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 完整妝容虛擬試妝 V1.0 | 2 |\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/template/look-vto": { "get": { "summary": "列出預先定義的範本。", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "page_size", "in": "query", "schema": { "type": "integer", "example": 20 }, "description": "這一頁要回傳的結果數量。有效值應介於 1 到 20 之間。預設為 20。" }, { "name": "starting_token", "in": "query", "schema": { "type": "string", "example": "73a3c9e69b89" }, "description": "目前頁面的令牌。第一頁以 `null` 開始，並使用上一個回應中的 `next_token` 開始下一頁" } ], "responses": { "200": { "$ref": "#/components/responses/TemplateResponse" }, "400": { "$ref": "#/components/responses/InvalidParameters" }, "401": { "$ref": "#/components/responses/InvalidApiKey" } } } }, "/s2s/v2.0/task/look-vto": { "post": { "summary": "執行 AI 完整妝容虛擬試妝任務。", "description": "這個端點使用範本與來源照片啟動完整妝容虛擬試妝流程。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。\n", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWithSingleTemplateAndSrcUrl" } } } }, "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/look-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" } ] }, "RunWithSingleTemplate": { "title": "RunWithSingleTemplate", "type": "object", "properties": { "template_id": { "type": "string", "description": "範本的 ID。請先列出預先定義的範本，然後使用某個範本的 id。\n", "example": "good_template_001" } }, "required": [ "template_id" ] }, "RunWithSingleTemplateAndSrcUrl": { "title": "RunWithSingleTemplateAndSrcUrl", "allOf": [ { "$ref": "#/components/schemas/RunWithSingleTemplate" }, { "$ref": "#/components/schemas/BasicRunTaskV2" } ] }, "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" } } } } }, "Template": { "type": "object", "properties": { "id": { "type": "string", "description": "範本的 ID。執行任務時將其作為 `template_id` 使用。", "example": "good_template_001" }, "thumb": { "type": "string", "description": "風格的縮略圖。" }, "title": { "type": "string", "description": "範本的標題。" }, "category_name": { "type": "string", "description": "範本的類別名稱。" } } }, "Style": { "type": "object", "properties": { "style_group_id": { "type": "integer", "description": "風格群組的 id。執行任務時將其作為 `style_group_id` 使用。" }, "style_id": { "type": "integer", "description": "風格的 id。執行任務時將其作為 `style_ids` 使用。" }, "info": { "type": "object", "properties": { "title": { "type": "string", "description": "風格名稱" }, "thumb": { "type": "string", "description": "風格的縮略圖" } }, "required": [ "title", "thumb" ] } }, "required": [ "style_group_id", "style_id", "info" ] }, "Category": { "type": "object", "properties": { "id": { "type": "integer", "description": "類別的 id。" }, "name": { "type": "string", "description": "類別的名稱。" }, "styles": { "type": "array", "description": "屬於這個類別的風格。", "items": { "$ref": "#/components/schemas/Style" } }, "sub_categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "子類別的 id。使用這個 id 查詢其內容。" }, "name": { "type": "string", "description": "子類別的名稱。" } }, "required": [ "id", "name" ] } } }, "required": [ "id", "name", "styles", "sub_categories" ] }, "TemplateResponseSchema": { "type": "object", "properties": { "status": { "type": "integer", "description": "回應狀態", "example": 200 }, "data": { "type": "object", "properties": { "templates": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "next_token": { "type": "string", "example": "73a3c9e69b89", "description": "查詢下一頁的令牌。" } } } } } }, "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" ] } } } } } }, "TemplateResponse": { "description": "成功取得風格", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateResponseSchema" } } } } } } }