AI 臉部塑型

整合指南

本指南將引導您完成：

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/

• 認證

• 使用 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

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

2. 準備特效範本

   • 前處理 輸出以像素座標表示的偵測邊界框。使用結果的索引，在稍後建立臉部塑型 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
     }
     }

3. 建立臉部塑型 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 度。

臉部自訂參數指南

說明： “左”與“右”指的是人物的視角，而非螢幕上觀看者的一側。

• 支援的格式與尺寸

• 錯誤代碼

• 環境與相依性

JS Camera Kit

點數消耗