# AI 虛擬耳環 # 概述 終極的 AI 虛擬耳環 頂尖的 AI 耳洞模擬器，用於虛擬耳環試戴與虛擬穿孔試戴 從 2D 圖片創造寫實且動態的耳環虛擬試戴，無需昂貴的 3D 建模。我們先進的演算法以精緻的光線效果與物理精確的動作，創造栩栩如生的虛擬試戴耳環 SKU。 ## 整合指南 本指南將引導您完成： * **端點：** `/s2s/v2.0/task/2d-vto/earring` * **認證：** 所有請求都需要 `Authorization: Bearer YOUR_API_KEY` * **工作流程：** 1. **準備自拍圖片：** 上傳圖片，或提供有效的圖片網址 2. **準備耳環圖片：** 上傳圖片，或提供耳環產品的有效圖片網址 3. **啟動 AI 任務並取得任務 ID：** 從回應中取得 `task_id` 。 4. **輪詢狀態（`GET`）：** 使用 `task_id` 查詢任務狀態。持續輪詢直到 `task_status` 為 `"success"` 或 `"error"` 。 --- * API Playground 使用我們的官方 playground 進行互動式探索與測試： **API Playground：** [http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-earring-virtual-try-on/) --- * 認證 - 使用 **Bearer Token** 將您的 API key 納入請求標頭： ``` Authorization: Bearer YOUR_API_KEY ``` 您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。 * 1. 上傳圖片 您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。 * 上傳端點 ``` POST /s2s/v2.0/file ``` 或者，若您已有公開的圖片網址，可跳過此步驟。 您可以直接上傳檔案到 File API 回應中提供的網址，然後使用 File API 回傳的對應 `src_file_id`，在後續呼叫 AI 任務。或在 VTO 任務內容中提供有效的圖片網址作為 `src_file_url`。`src_file_id` 或 `src_file_url` 將作為虛擬試戴的目標。 您也必須使用 `ref_file_ids` 或 `ref_file_urls` 提供另一張耳環產品圖片作為參考，以套用到您的 `src_file_id` 或 `src_file_url`。 AI 引擎支援為您的耳環產品圖片自動移除背景。不過，您可以為您的手部（`srcmsk_file_id` 或 `srcmsk_file_url`）或耳環產品（`refmsk_file_ids` 或 `refmsk_file_urls`）提供遮擋遮罩圖片檔案，以微調分割結果。 --- * 1. 建立耳環 VTO 任務並輪詢結果 當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。 * 建立任務端點 ``` POST /s2s/v2.0/task/2d-vto/earring ``` * 輪詢端點 ``` GET /s2s/v2.0/task/2d-vto/earring/{task_id} ``` --- ## 檔案規格與錯誤 * AI 虛擬耳環規範 **支援的耳環參考圖片** * 單個耳環的圖片，正面視角清晰且無遮擋。 * 所有參數（包括錨點、遮罩、位置等） **僅** 在參考圖片展示 **單個耳環** 佩戴時適用。 * 若試戴參考圖片展示 **兩邊耳環** ，所有參數將使用 **自動偵測與預設設定** 。 * 試戴 **兩邊耳環** 時，較清晰的耳朵將作為來源，另一邊則以其鏡像生成。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_01_41c943f9fc_037ffb1241.jpg) ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/earring_product_07_5476e0a156_a69e8e6549.jpg) **支援的自拍視角** * AI 虛擬耳環支援正面圖片，但側面圖片可達到最佳結果。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/Earring_restriction_cdf1de3c7b.png) **earring_wearing_location：長度為 2 的整數陣列** 指定自拍中耳環應放置的目標位置。 預設值：null（引擎預設） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/wearing_location_b4f6f4453a.jpg) **earring_scale：大於 0 的數值** 以公分控制耳環尺寸。 預設值：null（引擎預設） **earring_is_right_ear：boolean** indicating 耳環是否佩戴在右耳。預設佩戴在右耳。 預設值：true **earring_occluded_type：number（Enum：0、1、2）** 指定遮擋類型： 0 代表自動偵測 1 代表被遮擋 2 代表無遮擋 預設值：0 **earring_shadow_intensity：float（0.0 到 1.0）** 控制陰影強度： 0.0 代表無陰影 1.0 代表最大陰影 預設值：0.15 **earring_ambient_light_intensity：float（0.0 到 1.0）** 定義光線參考自拍圖片的程度： 0.0 忽略自拍圖片的光線 1.0 完全符合自拍圖片的光線與陰影渲染 預設值：1.0 **earring_anchor_point：以像素座標表示的一點陣列（選填）** 指定耳環產品圖片中的佩戴位置。 預設值：null（引擎預設） ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/anchor_point_787282aa19.jpg) --- * 支援的格式與尺寸 | AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 | | --- | --- | --- | --- | | AI 虛擬耳環 | 長邊 <= 4096 | < 10MB | jpg/jpeg/png | * 錯誤代碼 | 錯誤代碼 | 說明 | | --- | --- | | RUNTIME_ERROR | 耳環執行期間發生不如預期的錯誤 | | PHOTO_DETECTION_FAIL | 無法正確處理使用者照片，例如未偵測到手 | | OBJECT_DETECTION_FAIL | 無法正確處理物件照片，例如未偵測到產品 | | PHOTO_CHECK_INVALID | 使用者照片的姿勢或尺寸無效 | | INPUT_ERROR | 輸入檔案格式不正確 | | INPUT_MAIN_IMAGE_EMPTY | 需要使用者圖片 | * 環境與相依性 | 範例程式語言 / 工具 | 建議的執行環境版本 | | --- | --- | | cURL | - bash >= 3.2 - curl >= 7.58（現代 TLS/HTTP 支援） - jq >= 1.6（穩健的 JSON 解析） | | Node.js（JavaScript） | Node >= 18（支援全域 fetch） | | JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 | | PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json | | Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 | | Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 | --- ## JS Camera Kit --- ## 點數消耗 | AI 功能 | 消耗的點數 | | --- | --- | | AI 虛擬耳環 V1.0 | 單件佩戴 1 點 疊戴 2 點 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 使用標準的 'Bearer authentication'。請在標頭中放入您的 'API Key'：`Authorization:Bearer YOUR_API_KEY`。請注意 'Bearer' 與 'YOUR_API_KEY' 之間有一個空格。 Type: http Scheme: bearer ## Download OpenAPI description - [AI 虛擬耳環](https://docs.perfectcorp.com/_bundle/@l10n/zh-TW/reference/ai_earrings.yaml) ## V1.0 - [POST /s2s/v2.0/task/2d-vto/earring](https://docs.perfectcorp.com/zh-tw/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring/post.md): 這個端點啟動耳環虛擬試戴流程。您必須提供來源檔案與參考圖片（透過網址或檔案 ID），以及對位、陰影與佩戴位置的特定參數。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。 - [GET /s2s/v2.0/task/2d-vto/earring/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_earrings/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1earring~1%7Btask_id%7D/get.md)