# AI 虛擬戒指 # 概述 輕鬆建立您的 AR 戒指或訂婚戒指試戴體驗。您只需上傳圖片。選擇 2D 圖片，以最少的力氣達成輕鬆卻高品質的虛擬試戴體驗。 ## 整合指南 本指南將引導您完成： * **端點：** `/s2s/v2.0/task/2d-vto/ring` * **認證：** 所有請求都需要 `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-ring-virtual-try-on/](http://yce.makeupar.com/api-console/en/api-playground/ai-ring-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/ring ``` * 輪詢端點 ``` GET /s2s/v2.0/task/2d-vto/ring/{task_id} ``` --- ## 檔案規格與錯誤 * AI 虛擬戒指規範 **支援的戒指視角** 戒指圖片必須以四分之三正面視角（約 45 度）提供。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_product_01_9a4d0680f2_b46afe9a53.jpg) **支援的手部視角** 手背應完全可見，五根手指都清楚呈現且無任何遮擋。 ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_user_01_6d9893abd0_c7427cdb78.jpg) **ring_wearing_finger：integer（0–4）** 指定戒指戴在哪根手指： 0 = 拇指 1 = 食指 2 = 中指 3 = 無名指 4 = 小指 **ring_wearing_location：float（0.0–1.0）** 指示沿著手指的位置： 0.0 = 接近 MCP 關節（大指節） 1.0 = 接近 PIP 關節（中間關節） ![ring_wearing_location](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_wearing_location_59567be4af.jpg) **ring_shadow_intensity：float（0.0–1.0）** 控制陰影強度： 0.0 = 無陰影 1.0 = 最大陰影 預設：0.15 **ring_ambient_light_intensity：float（0.0–1.0）** 定義光線參考目標手部圖片的程度： 0.0 = 忽略手部圖片的光線 1.0 = 完全配合手部圖片的光線與陰影渲染 預設：1.0 **ring_anchor_point：以像素座標表示的兩個點的陣列（選填）** 標示戒指接觸手指的內緣，指定左與右的點。這對於寬版或厚版戒指特別有用。 若未提供此參數，AI 引擎會自動偵測錨點。 ![ring_anchor_point](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/ring_anchor_point_e6eb241ef8.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/ring_vto.yaml) ## V1.0 - [POST /s2s/v2.0/file/2d-vto/ring](https://docs.perfectcorp.com/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1file~12d-vto~1ring/post.md): 要上傳新檔案，您必須先使用 File API。它會提供一個網址——請使用該網址上傳您的檔案。上傳完成後，您可以使用同一個回應中的 file_id，開始使用我們的 AI 功能。 - [POST /s2s/v2.0/task/2d-vto/ring](https://docs.perfectcorp.com/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring/post.md): AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook)。 若您的整合不支援 webhook 或無法使用 - [GET /s2s/v2.0/task/2d-vto/ring/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ring_vto/v1.0/paths/~1s2s~1v2.0~1task~12d-vto~1ring~1%7Btask_id%7D/get.md)