常見問題

AI 虛擬髮型

概述

使用最新的 AI 技術嘗試多種髮型，同時滿足女性與男性，符合不同的性別與風格偏好。探索風格的世界：捲髮、長髮、平頭等。我們 AI 驅動的髮型變換器讓您可以輕鬆嘗試。現在就找到您的理想髮型！

整合指南

API Playground 您可以使用 API Playground 測試 AI 虛擬髮型功能。這讓您可以實驗自己的想法，並更深入了解試戴流程。

在此存取 API Playground： https://yce.makeupar.com/api-console/en/api-playground/ai-hair-style-generator/

API 工作流程本指南將引導您完成：

AI 虛擬髮型 API 的工作流程：

端點： /s2s/v2.1/task/hair-transfer

需要認證： Authorization: Bearer YOUR_API_KEY

工作流程步驟：

圖片上傳準備：
- 流程從準備自拍開始。
列出預先定義的範本，或使用您自己的參考照片 選擇參考來源 造型參考有兩種選項：

選項	使用情境	實作建議
預先定義的範本（`template_id`）	快速開始（例如「捲髮短髮」、「側分瀏海」）	呼叫 `/s2s/v2.1/task/template/hair-transfer` 並選擇 `template_id`。
自訂參考圖片（`ref_file_url` / `ref_file_id`）	使用者上傳自己的風格照片，或使用提供的圖片連結	透過相同的檔案 API 上傳；若您的參考圖片已託管在線上，請使用 `ref_file_url`。

啟動 AI 任務並取得任務 ID：
- 透過 HTTP POST 請求，將上傳的圖片與風格設定傳送到 /s2s/v2.0/file。
- 在回應中取得唯一的任務 ID，用以識別這次互動。
輪詢任務狀態（持續檢查）：
- 使用取得的 task_id，透過 HTTP GET 請求（例如 GET /task/${task_id}）定期輪詢任務狀態。
- 持續監控：
  - Task_status = "success"（流程完成）。
  - Task_status = "error"（視情況解決或重試）。
- 狀態轉為成功後，相應更新工作流程。

這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。

認證

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

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

API 使用指南

本指南說明如何使用 AI 虛擬髮型 API 上傳圖片、準備參考圖片，以及建立虛擬試戴任務。

步驟 1. 使用 File API 上傳檔案，或提供有效的圖片網址

使用 File API（/s2s/v2.0/file）上傳目標使用者圖片。

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

圖片需求：

上傳高解析度的自拍照片。
確保照片清楚呈現整個身體。
避免有多人干擾的物件背景。

請求範例：

curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "selfie_01_3dbd1b6683.jpg",
        "file_size": 547541
      }
    ]
  }'

步驟 2. 取得 File API 回應

回應包含：

用於建立 AI 任務的 file_id。
用於上傳實際圖片檔案的 requests.url。

回應範例：

{
  "status": 200,
  "data": {
    "files": [
      {
        "content_type": "image/jpg",
        "file_name": "full_body_photo_01_3dbd1b6683.jpg",
        "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud",
        "requests": [
          {
            "method": "PUT",
            "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...",
            "headers": {
              "Content-Length": "547541",
              "Content-Type": "image/jpg"
            }
          }
        ]
      }
    ]
  }
}

步驟 3. 上傳圖片到提供的網址

使用 File API 回應中的 requests.url 上傳圖片：

curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \
  --header 'Content-Type: image/jpg' \
  --header 'Content-Length: 547541' \
  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'

步驟 4. 準備參考圖片
- 4.1 取得預先定義的圖片範本

使用 範本 API（/s2s/v2.1/task/template/hair-transfer）取得預先定義的參考範本清單：

curl --request GET \
  --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \
  --header 'Authorization: Bearer YOUR_API_KEY'

4.2 上傳參考圖片

您可以：

使用 File API（/s2s/v2.0/file）上傳參考圖片，或
提供有效的圖片網址。

支援的圖片：

另一張自拍照片作為參考圖片。

詳細規格請參考 檔案規格與錯誤。

步驟 5. 建立 AI 虛擬髮型任務

使用 AI 任務 API（/s2s/v2.1/task/hair-transfer）建立虛擬試戴任務。

參數：

使用者圖片：src_file_id 或 src_file_url。
參考圖片：ref_file_id、ref_file_url 或 template_id。

請求範例：

curl --request POST \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
    "src_file_url": "https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg",
    "ref_file_url": "https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png"
  }'

回應範例：

{
  "status": 200,
  "data": {
    "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT"
  }
}

步驟 6. 輪詢任務結果

使用任務 ID 查詢狀態：

curl --request GET \
  --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/<YOUR_TASK_ID> \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'content-type: application/json'

步驟 7. 取得結果

成功的回應會包含結果圖片的下載網址：

{
  "status": 200,
  "data": {
    "error": null,
    "results": {
      "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..."
    },
    "task_status": "success"
  }
}

API Key 無效的錯誤回應：

{
  "status": 401,
  "error": "Unauthorized",
  "error_code": "InvalidAccessToken"
}

應用案例：應用案例：

拍攝建議：

檔案規格與錯誤

支援的格式與尺寸

AI 功能	支援的尺寸	支援的檔案大小	支援的格式
AI 虛擬髮型	長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部	< 10MB	jpg/jpeg

錯誤代碼

錯誤代碼	說明
error_no_shoulder	來源圖片中肩膀不可見
error_large_face_angle	上傳圖片的臉部角度過大
error_insufficient_landmarks	無法在來源圖片偵測足夠的臉部或身體標記點
error_hair_too_short	輸入的頭髮過短
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 虛擬髮型支援兩種指定理想髮型的方法：

上傳您自己的參考圖片 您可以透過 File API（/s2s/v2.0/file）上傳高解析度的自拍或風格照片（例如展示目標髮型的人）。上傳後，在建立 AI 任務時，使用回傳的 file_id 或公開網址作為參考來源。
提供有效的圖片網址 若您的參考圖片已託管在線上（例如在您自己的伺服器或 CDN 上），您可以直接在請求內容的 ref_file_url 欄位提供其 HTTPS 網址。

透過 /s2s/v2.1/task/hair-transfer 提交任務時，請包含以下其中之一：