AI 虛擬耳環

整合指南

本指南將引導您完成：

• 端點： /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/

• 認證

• 使用 Bearer Token 將您的 API key 納入請求標頭：
  Authorization: Bearer YOUR_API_KEY

您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。

• 1. 上傳圖片

您可以直接上傳檔案到伺服器，或在 VTO 任務內容中提供有效的圖片網址。

• 上傳端點

或者，若您已有公開的圖片網址，可跳過此步驟。

您可以直接上傳檔案到 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）提供遮擋遮罩圖片檔案，以微調分割結果。

• 2. 建立耳環 VTO 任務並輪詢結果

當您取得圖片與範本 ID 後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 success 或 error。

• 建立任務端點

• 輪詢端點

檔案規格與錯誤

• AI 虛擬耳環規範

支援的耳環參考圖片

• 單個耳環的圖片，正面視角清晰且無遮擋。
• 所有參數（包括錨點、遮罩、位置等）僅在參考圖片展示單個耳環佩戴時適用。
• 若試戴參考圖片展示兩邊耳環，所有參數將使用自動偵測與預設設定。
• 試戴兩邊耳環時，較清晰的耳朵將作為來源，另一邊則以其鏡像生成。

支援的自拍視角

• AI 虛擬耳環支援正面圖片，但側面圖片可達到最佳結果。

earring_wearing_location：長度為 2 的整數陣列 指定自拍中耳環應放置的目標位置。 預設值：null（引擎預設）

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（引擎預設）

• 支援的格式與尺寸

• 錯誤代碼

• 環境與相依性

JS Camera Kit

點數消耗