# AI 虛擬鬍鬚造型 # 概述 男士鬍型生成的 AI 模擬 AI 演算法也賦能男性完全自由地，以高度精緻的鬍型模擬技術虛擬嘗試不同的鬍型，包括整齊短鬍、短鬚、全鬍、圓鬍、八字鬍、山羊鬍等。 購物者也能看見前後結果，無需承擔動刀的承諾。 鬍型濾鏡包括八字鬍、短方鬍、鴨尾鬍、圓鬍等十余種。 ## 整合指南 1. **上傳自拍** 您可以透過兩種方式之一提供來源圖片： - **使用現有的公開圖片網址** 無需上傳，您可以在啟動 AI 任務時直接提供可公開存取的圖片網址。 - **透過 File API 上傳** 使用端點： ``` POST /s2s/v2.0/file ``` 這會回傳用於後續任務執行的 `file_id`。 - ***重要***：僅呼叫 File API 並不會上傳您的檔案。您必須**手動上傳**檔案到**File API 回應中提供的網址**。該網址就是您的上傳目的地，請確保檔案成功傳輸到該處後再繼續。 在呼叫 AI API 之前，請確保您的檔案已成功上傳。使用 File API 取得上傳網址，然後將檔案上傳到該位置。上傳完成後，您會在回應中取得 ***file_id***，這個 ID 就是您用於存取該檔案相關 AI 功能的依據。 > **警告：** 請注意，若您未將檔案上傳到 File API 回應中提供的網址，使用 AI API 時會得到 500 Server Error / unknown_internal_error 或 404 Not Found 錯誤。 1. **列出預先定義的風格** * 使用 /s2s/v2.0/task/template/beard-style 取得預先定義的範本清單，並選擇 `template_id` 執行 AI 任務。 2. **執行 AI 任務以取得任務 ID** 使用 /s2s/v2.0/task/beard-style 執行 AI 任務。對於目標使用者圖片，提供 `src_file_url` 或 `src_file_id`。並提供要套用的 `template_id` 以取得 `task_id`。 3. **輪詢以查詢任務狀態直到成功或失敗** 使用 `task_id`，透過輪詢 GET /s2s/v2.0/task/beard-style 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 running，此階段不會消耗點數。 您也可以實作 webhook，在 AI 任務成功或失敗時接收通知。細節請參考 **[Webhook](../../../develop/webhook)** 章節。 > **警告：** 必須在任務的保留期間內輪詢以查詢任務狀態。若在保留期間內沒有輪詢請求，任務將會逾時，即使任務已成功處理。您的點數仍會被消耗。 > **警告：** 若您查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，執行 AI 任務後，您必須在保留期間內輪詢以查詢狀態，直到狀態變為 success 或 error。 4. **成功後取得 AI 任務的結果** 引擎處理您的輸入檔案並生成結果影像後，任務狀態會變為 success。您會取得處理後圖片的網址。 --- ## 檔案規格與錯誤 * 支援的格式與尺寸 | AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 | | --- | --- | --- | --- | | AI 虛擬鬍鬚造型 | 解析度：長邊 < 1024 臉寬 > 256 臉部姿勢：-30 < yaw < 30, 僅限單張臉部, 需呈現完整臉部 | < 10MB | jpg/jpeg | * 錯誤代碼 | 錯誤代碼 | 說明 | | --- | --- | | error_no_face | 來源圖片中臉部不可見 | | error_src_face_too_small | 臉部過小 | | error_inference | 鬍型移除錯誤或鬍型生成錯誤 | | error_face_pose | 來源圖片的臉部姿勢不受支援 | * 環境與相依性 | 範例程式語言 / 工具 | 建議的執行環境版本 | | --- | --- | | 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 | --- ## 點數消耗 | AI 功能 | 消耗的點數 | | --- | --- | | AI 虛擬鬍鬚造型 V1.0 | 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_beard_style.yaml) ## V1.0 - [GET /s2s/v2.0/task/template/beard-style](https://docs.perfectcorp.com/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1template~1beard-style/get.md) - [POST /s2s/v2.0/task/beard-style](https://docs.perfectcorp.com/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style/post.md): AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook)。 若您的整合不支援 webhook 或無法使用 - [GET /s2s/v2.0/task/beard-style/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_beard_style/v1.0/paths/~1s2s~1v2.0~1task~1beard-style~1%7Btask_id%7D/get.md)