# AI 臉部塑型 # 概述 AI 臉部塑型 API 讓您可以程式化地重塑臉部特徵——眼睛、鼻子、嘴唇、下顎線，或整張臉——達到像素級的精準控制。用它為鼻整形、下巴填充、嘴唇豐唇、眉部提拉及其他美學療程工作流程，產生前後視覺化。 * 鼻整形（隆鼻） 我們的線上鼻整形模擬器提供醫療級的精準調整。不同於一般的照片編輯應用，它能全面模擬特定細節，包括鼻樑、提拉與鼻翼。透過超寫實的預覽，客戶能在諮詢前清楚呈現並探索理想的比例。 * 下巴填充 透過我們的線上模擬器，您可以預覽下巴填充達成的理想比例。微調下巴長度與下巴形狀，呈現後縮或短下巴的改善。在接受任何皮膚填充療程前，找到平衡臉部側影的最佳方案。 * 嘴唇填充 使用者可嘗試不同的嘴唇填充體積與形狀，模擬更飽滿嘴唇的外觀，幫助他們在進行療程前決定理想的結果。 * 眉部提拉手術 此功能讓使用者預覽眉部提拉的結果，透過提拉與重塑眉毛，創造更年輕、回春的外觀。 ## 整合指南 本指南將引導您完成： AI 臉部塑型 API 的工作流程： **端點：** `/s2s/v2.0/file` **需要認證：** `Authorization: Bearer YOUR_API_KEY` **工作流程步驟：** 1. **圖片上傳準備：** - 準備要上傳的自拍圖片。 - 呼叫 File API `/s2s/v2.0/file` 取得上傳網址與相關的 `file_id` 。 - 使用提供的上傳網址上傳自拍圖片。 2. **多張臉部的選填前處理：** - 若圖片中有多於一張臉部，請對自拍圖片進行前處理。 3. **臉部塑型特效設定：** - 先選擇眼睛、臉、嘴唇或鼻子的合適臉部塑型參數。 4. **啟動 AI 任務並取得任務 ID：** - 透過 HTTP POST 請求，將 `file_id` 與所選特效設定傳送到 `/s2s/v2.0/task/face-reshape` 。 - 在回應中取得唯一的任務 ID，用以識別這次互動。 5. **輪詢任務狀態（持續檢查）：** - 使用取得的 `task_id` ，透過 HTTP GET 請求（例如 `GET /s2s/v2.0/task/face-reshape/${task_id}` ）定期輪詢任務狀態。 - 持續監控： - `Task_status = "success"` （流程完成）。 - `Task_status = "error"` （視情況解決或重試）。 - 狀態轉為成功後，相應更新工作流程。 這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。 --- * API Playground 使用我們的官方 playground 進行互動式探索與測試： **API Playground：** [http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/](http://yce.makeupar.com/api-console/en/api-playground/ai-face-reshape/) --- * 認證 - 使用 **Bearer Token** 將您的 API key 納入請求標頭： ``` Authorization: Bearer YOUR_API_KEY ``` 您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。 1. 上傳圖片 您可以直接上傳檔案到伺服器，或在 AI 任務內容中提供有效的圖片網址。 * 上傳端點 ``` POST /s2s/v2.0/file ``` 或者，若您已有公開的圖片網址，可跳過此步驟。 --- 1. 準備特效範本 * 前處理 輸出以像素座標表示的偵測邊界框。使用結果的索引，在稍後建立臉部塑型 AI 任務。 ``` { "timed": number, "result": [ { "left": number, "top": number, "width": number, "height": number } ] } ``` * 特效範本 JSON Schema ``` { "version": "1.0", "index": 0, "features": {}, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50, }, } ``` index：來自前處理的偵測臉部索引。選填，預設 0。 features：必要，至少 1 個非零的臉部塑型參數，不可全為零。 skin_smooth_strength: 0~100 skin_smooth_color_intensity: 0~100 * 特效格式 - 臉 預設範圍：-100~100 顴骨與下顎的範圍：0~100 所有功能值不可同時為零，至少有一個功能值必須非零 ``` { "cheekbones": 0, "jaw": 0, "face_reshape_left": 0, "face_reshape_right": 0, "face_width": 0, "chin_reshape_left": 0, "chin_reshape_right": 0, "chin_length": 0, } ``` - 眼睛 預設範圍：-100~100 所有功能值不可同時為零，至少有一個功能值必須非零 ``` { "eye_size_left": 0, "eye_size_right": 0, "eye_distance": 0, "eye_angle": 0, "eye_height": 0, "eye_width": 0, } ``` - 鼻子 預設範圍：-100~100 所有功能值不可同時為零，至少有一個功能值必須非零 ``` { "nose_bridge_width": 0, "nose_lift": 0, "nose_size": 0, "nose_tip": 0, "nose_tip_width": 0, "nose_wing": 0 } ``` - 嘴唇 預設範圍：-100~100 所有功能值不可同時為零，至少有一個功能值必須非零 ``` { "lip_size": 0, "lip_width": 0, "lip_peak": 0, "lip_height_top": 0, "lip_height_bottom": 0, } ``` * 內容範例（可直接發送） ``` { "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/face_reshape_01_85c8ffc055.jpg", "version": "1.0", "source": "yco", "features": { "eye_size_left": 80, "eye_size_right": 80, "eye_width": 0, "eye_height": 0, "eye_distance": 0, "eye_angle": 0, "face_reshape_left": 0, "face_reshape_right": 0, "chin_reshape_left": 20, "chin_reshape_right": 20, "chin_length": 0, "face_width": -30, "cheekbones": 0, "jaw": 0, "lip_size": 10, "lip_width": 40, "lip_height_top": 10, "lip_height_bottom": 10, "lip_peak": -10, "nose_size": 30, "nose_lift": -20, "nose_bridge_width": 10, "nose_tip": -10, "nose_wing": 30, "nose_tip_width": 30 }, "global": { "skin_smooth_strength": 50, "skin_smooth_color_intensity": 50 } } ``` 2. 建立臉部塑型 AI 任務並輪詢結果 當您取得圖片與完整的特效內容後，即可建立任務。API 以非同步方式處理請求。您必須輪詢任務狀態，直到達到 `success` 或 `error`。 * 建立任務端點 ``` POST /s2s/v2.0/task/face-reshape ``` * 輪詢端點 ``` GET /s2s/v2.0/task/face-reshape/{task_id} ``` --- ## 檔案規格與錯誤 * AI 臉部塑型規範 **支援的自拍視角** 自拍照片中，臉部的寬與高需大於圖片寬度與高度的 1/20。 pitch、yaw 與 rolling 的臉部角度小於 30 度。 ![](https://plugins-media.makeupar.com/strapi/assets/thumbnail_face_reshape_01_85c8ffc055.jpg) **臉部自訂參數指南** | 類別 | 參數 | 功能 | 最小 (-100 / 0) | 最大 (100) | | --- | --- | --- | --- | --- | | 眼睛 | 大小（左/右） | 調整每隻眼睛的整體大小 | 小 | 大 | | 眼睛 | 寬度 | 調整水平跨度 | 窄 | 寬 | | 眼睛 | 高度 | 調整垂直跨度 | 窄／平 | 圓／高 | | 眼睛 | 距離 | 調整兩眼間的間距 | 靠近 | 分開 | | 眼睛 | 角度 | 調整旋轉傾斜 | 內傾 | 外傾 | | 臉 | 大小（左/右） | 調整臉部每側的大小 | 小 | 大 | | 臉 | 下巴形狀（左/右） | 調整下巴輪廓寬度 | 窄 | 寬 | | 臉 | 下巴長度 | 調整下巴的垂直長度 | 短 | 長 | | 臉 | 寬度 | 調整整體臉部寬度 | 窄 | 寬 | | 臉 | 顴骨 | 調整顴骨的明顯程度 | 原始 (0) | 內收 | | 臉 | 下顎 | 調整下顎線的明顯程度 | 原始 (0) | 內收 | | 嘴唇 | 大小 | 調整嘴唇的整體體積 | 小 | 大 | | 嘴唇 | 寬度 | 調整水平跨度 | 窄 | 寬 | | 嘴唇 | 上唇高度 | 調整上唇厚度 | 薄 | 飽滿 | | 嘴唇 | 下唇高度 | 調整下唇厚度 | 薄 | 飽滿 | | 嘴唇 | 唇峰 | 調整丘比特弓的鮮明度 | 平滑 | 明確 | | 鼻子 | 大小 | 調整鼻子的整體大小 | 小 | 大 | | 鼻子 | 提拉 | 調整垂直位置 | 低 | 高 | | 鼻子 | 鼻樑 | 調整鼻樑寬度 | 窄 | 寬 | | 鼻子 | 鼻尖 | 調整鼻尖的垂直角度 | 向上 | 向下 | | 鼻子 | 鼻翼 | 調整鼻孔寬度 | 窄 | 寬 | | 鼻子 | 寬度 | 調整鼻尖的寬度 | 窄 | 寬 | **說明：** *“左”與“右”指的是人物的視角，而非螢幕上觀看者的一側。* --- * 支援的格式與尺寸 | 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 | --- 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_face_reshape.yaml) ## V1.0 - [POST /s2s/v2.0/task/face-reshape/pre-process](https://docs.perfectcorp.com/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process/post.md): 當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 `index` 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。 前處理任務會偵測來源照片中的候選目標，並在 `data.results.result` 中回傳它們的座標。結果陣列中的每個項目代表一個被偵測到的目標。檢視回傳的座標，將它們對應到來源 - [GET /s2s/v2.0/task/face-reshape/pre-process/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1pre-process~1%7Btask_id%7D/get.md): 當來源照片可能包含超過一個有效目標，或您的整合需要明確選擇哪個被偵測到的目標接受特效時，請使用前處理任務。對於單一目標的圖片，當功能支援預設的 `index` 值，且您的應用程式不需要手動選擇目標時，可以跳過前處理。 前處理任務會偵測來源照片中的候選目標，並在 `data.results.result` 中回傳它們的座標。結果陣列中的每個項目代表一個被偵測到的目標。檢視回傳的座標，將它們對應到來源 - [POST /s2s/v2.0/task/face-reshape](https://docs.perfectcorp.com/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape/post.md): AI 任務是非同步的。當功能支援 webhook 時，請優先使用以 webhook 為基礎的完成處理。設定您的 webhook 端點、驗證 webhook 簽章，並在收到 `success` 或 `error` 通知後，使用收到的 `task_id` 查詢任務結果。設定與驗證細節請見 [webhook 整合指南](/develop/webhook)。 若您的整合不支援 webhook 或無法使用 - [GET /s2s/v2.0/task/face-reshape/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_face_reshape/v1.0/paths/~1s2s~1v2.0~1task~1face-reshape~1%7Btask_id%7D/get.md)