{
"openapi": "3.0.0",
"info": {
"title": "AI 虛擬美瞳變色片",
"description": "# 概述\nAI 虛擬美瞳變色片虛擬模擬透過精準偵測虹膜、保留自然反射、精確模擬鏡片在不虹膜顏色上的不透明度與混合，並讓使用者探索從細微變化到鮮豔藍色轉變的各種色調，全部整合在單一專業級 AI API 中，提供即時且極其逼真的隱形眼鏡試戴體驗。\n\n\n\n**隱形眼鏡虛擬模擬**\n\n使用我們的 AI 驅動虛擬試戴工具，即時改變眼色。AI 虛擬美瞳變色片透過精準偵測虹膜並套用自然、逼真的色彩調整，帶來極其逼真的結果，讓購物者無需實體樣品即可探索新風格。\n\n**極其逼真的輸出** \n系統保留自然的眼部反射以呈現真實結果，確保每次色彩變化都栩栩如生。\n\n**進階隱形眼鏡濾鏡模擬** \n隱形眼鏡濾鏡能精確重現不同虹膜底色下的不透明度與混合效果，讓顧客以逼真的層次與色調虛擬試戴全系列鏡片。\n\n**不僅僅是改變眼色** \n這項技術超越了簡單的濾鏡，提供專業級的虛擬鏡片體驗，提升顧客信心並提高轉換率。\n\n---\n\n## 整合指南\n\n* 拍攝自拍\n\n * 在適當光線下正對鏡頭。\n * 使用 JS Camera Kit 拍攝照片。\n\n* 準備您的鏡片風格圖\n\n* 提供**一張清晰的鏡片風格圖片**：\n\n * 格式：**PNG**（建議：已移除背景）\n * 尺寸：**200 × 200 ≤ W × H ≤ 600 × 600**\n * 檔案大小：**< 10 MB**\n\n **範例：**\n\n \n \n\n* 透過 ***/s2s/v2.0/file*** API 取得上傳網址與檔案 ID\n\n 使用檔案 API 回應中回傳的上傳網址，上傳下列檔案：\n * 您的自拍照片\n * 鏡片風格圖片\n\n* 執行 AI 任務 ***/s2s/v2.0/task/eye-color-vto***\n\n 使用檔案 ID 或圖片網址作為輸入來源執行 AI 任務。依需求設定特效參數。\n\n* 輪詢任務狀態\n\n 使用回傳的 **task\\_id** 監控任務進度。 \n 輪詢 **GET /task/eye-color-vto** 以查詢引擎狀態。 \n 任務會維持在**「執行中」**狀態，直到完成。任務執行期間不會消耗點數。\n\n\n\n\n\n\n* **應用情境範例**\n\n AI 虛擬美瞳變色片虛擬模擬改變了顧客選購彩色隱形眼鏡的方式。流程簡單直觀、具互動性，且使用者幾乎不需費力。\n\n - 步驟 1：選擇您喜愛的顏色\n 顧客抵達您的網站並瀏覽您的商品後，即可選擇他們想試戴的色調。無論是細微的淡褐、鮮豔的綠色，或冰涼的藍色，他們都能探索多種顏色。\n\n - 步驟 2：開啟虛擬試戴鏡頭\n 只需一點擊，虛擬試戴工具即啟動。無需複雜的設定說明或額外下載。\n\n - 步驟 3：使用即時鏡頭或上傳照片\n 使用者可選擇即時鏡頭體驗，或上傳照片來虛擬試戴彩色隱形眼鏡。此功能以精準的準確度重現現實效果，確保他們看見每個色調在自然環境中的樣子。\n\n \n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|類型|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n|AI 虛擬美瞳變色片虛擬模擬|自拍圖片：
* 長邊 ≤ 1920 px
* 短邊 ≥ 320 px
鏡片風格圖片：
* 檔案格式：PNG
* 解析度：200 × 200 ≤ W × H ≤ 600 × 600 px|< 10MB|jpg/png|\n\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n| ---- | ---- |\n|error_below_min_image_size|若您的圖片寬或高小於 320 像素，尺寸過小無法使用|\n|error_face_position_invalid|您的臉部必須在圖片中完全可見，不可有任何部分被裁切|\n|error_face_position_too_small|您照片中的臉部太小，無法妥善分析|\n|error_face_position_out_of_boundary|您的臉部過大，或部分超出照片邊緣|\n|error_insufficient_lighting|光線過暗，導致難以分析|\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"
}
],
"tags": [
{
"name": "V1.0",
"description": "以 AI 驅動的虛擬美瞳變色片功能。"
}
],
"paths": {
"/s2s/v2.0/task/eye-color-vto": {
"post": {
"summary": "執行 AI 虛擬美瞳變色片任務。",
"description": "AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook.md)。\n\n若您的整合不支援 webhook 或無法使用 webhook，請實作輪詢。送出 AI 任務後，以固定間隔（例如每 10 秒）輪詢狀態端點，直到任務狀態為 `success` 或 `error`。\n",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2WithRequiredRef"
},
{
"type": "object",
"required": [
"version",
"effect"
],
"properties": {
"version": {
"type": "string",
"enum": [
"1.0"
]
},
"effect": {
"type": "object",
"required": [
"intensity"
],
"properties": {
"intensity": {
"type": "integer",
"maximum": 100,
"minimum": 1
},
"enlargement": {
"type": "integer",
"maximum": 100,
"minimum": 0,
"default": 0
},
"skin_smooth_strength": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"default": 50
},
"skin_smooth_color_intensity": {
"type": "integer",
"minimum": 0,
"maximum": 100,
"default": 50
}
}
}
}
}
]
}
}
}
},
"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/eye-color-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": {
"allOf": [
{
"$ref": "#/components/schemas/TaskStatusResponseV2"
},
{
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"results": {
"type": "object",
"properties": {
"timed": {
"type": "number"
},
"timed_apply": {
"type": "number"
}
}
}
}
}
}
}
]
}
}
}
},
"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": {
"BasicRunTaskV2SrcFileUrl": {
"type": "object",
"required": [
"src_file_url"
],
"properties": {
"src_file_url": {
"type": "string",
"description": "要執行任務的檔案網址。該網址應可公開存取。",
"example": "https://example.com/selfie.jpg"
}
}
},
"BasicRunTaskV2RefFileUrl": {
"type": "object",
"properties": {
"ref_file_url": {
"type": "string",
"description": "執行任務所用參考檔案的網址。該網址需可公開存取。",
"example": "https://example.com/accessory.jpg"
}
}
},
"BasicRunTaskV2RefFileId": {
"type": "object",
"properties": {
"ref_file_id": {
"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="
}
}
},
"BasicRunTaskV2WithRequiredRef": {
"title": "BasicRunTaskV2WithRef",
"anyOf": [
{
"allOf": [
{
"title": "Run task with src file url & ref file url",
"required": [
"ref_file_url"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl"
}
]
},
{
"allOf": [
{
"title": "Run task with src file url & ref file ID",
"required": [
"ref_file_id"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileId"
}
]
},
{
"allOf": [
{
"title": "Run task with src file ID & ref file url",
"required": [
"ref_file_url"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileUrl"
}
]
},
{
"allOf": [
{
"title": "Run task with src file ID & ref file ID",
"required": [
"ref_file_id"
]
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2RefFileId"
}
]
}
]
},
"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"
}
}
}
}
}
}
}
}
}