{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-@l10n/zh-TW/reference/ai_hairstyle.yaml","sidebar":"sidebar-@l10n/zh-TW/reference/sidebars.yaml"},"props":{"definitionId":"@l10n/zh-TW/reference/ai_hairstyle.yaml","settings":{"baseUrlPath":"/zh-tw/reference/ai_hairstyle"},"disableAutoScroll":true,"seo":{"title":"AI 虛擬髮型","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI 虛擬髮型","version":"","description":"# 概述\n使用最新的 AI 技術嘗試多種髮型，同時滿足女性與男性，符合不同的性別與風格偏好。\n探索風格的世界：捲髮、長髮、平頭等。我們 AI 驅動的髮型變換器讓您可以輕鬆嘗試。現在就找到您的理想髮型！\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v3_poster_bb1c7aad10.jpg)\n\n---\n\n## 整合指南\n\n* API Playground\n您可以使用 API Playground 測試 AI 虛擬髮型功能。這讓您可以實驗自己的想法，並更深入了解試戴流程。\n\n在此存取 API Playground：\n\n\n---\n\n* API 工作流程\n本指南將引導您完成：\n\nAI 虛擬髮型 API 的工作流程：\n\n**端點：** `/s2s/v2.1/task/hair-transfer`\n\n**需要認證：** `Authorization: Bearer YOUR_API_KEY`\n\n**工作流程步驟：**\n\n1. **圖片上傳準備：**\n - 流程從準備自拍開始。\n\n2. **列出預先定義的範本，或使用您自己的參考照片**\n **選擇參考來源**\n造型參考有兩種選項：\n\n| 選項 | 使用情境 | 實作建議 |\n|-------|-----------|---------------------|\n| **預先定義的範本**（`template_id`） | 快速開始（例如「捲髮短髮」、「側分瀏海」） | 呼叫 `/s2s/v2.1/task/template/hair-transfer` 並選擇 `template_id`。 |\n| **自訂參考圖片**（`ref_file_url` / `ref_file_id`） | 使用者上傳自己的風格照片，或使用提供的圖片連結 | 透過相同的檔案 API 上傳；
若您的參考圖片已託管在線上，請使用 `ref_file_url`。 |\n\n3. **啟動 AI 任務並取得任務 ID：**\n - 透過 HTTP POST 請求，將上傳的圖片與風格設定傳送到 `/s2s/v2.0/file`。\n - 在回應中取得唯一的任務 ID，用以識別這次互動。\n\n4. **輪詢任務狀態（持續檢查）：**\n - 使用取得的 `task_id`，透過 HTTP GET 請求（例如 `GET /task/${task_id}`）定期輪詢任務狀態。\n - 持續監控：\n - `Task_status = \"success\"`（流程完成）。\n - `Task_status = \"error\"`（視情況解決或重試）。\n - 狀態轉為成功後，相應更新工作流程。\n\n這個結構化的工作流程確保與使用者輸入的高效整合、任務的自動化監控，以及無縫取得結果。\n\n---\n\n* 認證\n- 使用 **Bearer Token** 將您的 API key 納入請求標頭：\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\n您可以在 https://yce.makeupar.com/api-console/en/api-keys/ 找到您的 API Key。\n\n---\n\n* API 使用指南\n\n本指南說明如何使用 AI 虛擬髮型 API 上傳圖片、準備參考圖片，以及建立虛擬試戴任務。\n\n***\n\n * 步驟 1. 使用 File API 上傳檔案，或提供有效的圖片網址\n\n使用 **File API**（`/s2s/v2.0/file`）上傳目標使用者圖片。\n\n或者，若您已有公開的圖片網址，可跳過步驟 1 到 3。\n\n**圖片需求：**\n\n* 上傳高解析度的自拍照片。\n* 確保照片清楚呈現整個身體。\n* 避免有多人干擾的物件背景。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * 步驟 2. 取得 File API 回應\n\n回應包含：\n\n* 用於建立 AI 任務的 `file_id`。\n* 用於上傳實際圖片檔案的 `requests.url`。\n\n**回應範例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"requests\": [\n {\n \"method\": \"PUT\",\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n \"headers\": {\n \"Content-Length\": \"547541\",\n \"Content-Type\": \"image/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * 步驟 3. 上傳圖片到提供的網址\n\n使用 File API 回應中的 `requests.url` 上傳圖片：\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * 步驟 4. 準備參考圖片\n\n * 4.1 取得預先定義的圖片範本\n\n使用 **範本 API**（`/s2s/v2.1/task/template/hair-transfer`）取得預先定義的參考範本清單：\n\n```bash\ncurl --request GET \\\n --url 'https://yce-api-01.makeupar.com/s2s/v2.1/task/template/hair-transfer?page_size=20&starting_token=73a3c9e69b89' \\\n --header 'Authorization: Bearer YOUR_API_KEY'\n```\n\n * 4.2 上傳參考圖片\n\n您可以：\n\n* 使用 File API（`/s2s/v2.0/file`）上傳參考圖片，或\n* 提供有效的圖片網址。\n\n**支援的圖片：**\n\n* 另一張自拍照片作為參考圖片。\n\n詳細規格請參考 **[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**。\n\n***\n\n * 步驟 5. 建立 AI 虛擬髮型任務\n\n使用 **AI 任務 API**（`/s2s/v2.1/task/hair-transfer`）建立虛擬試戴任務。\n\n**參數：**\n\n* 使用者圖片：`src_file_id` 或 `src_file_url`。\n* 參考圖片：`ref_file_id`、`ref_file_url` 或 `template_id`。\n\n**請求範例：**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/selfie_03_cccd5d4803.jpeg\",\n \"ref_file_url\": \"https://plugins-media.makeupar.com/strapi/assets/style_reference_full_body_01_5a000d999f.png\"\n }'\n```\n\n**回應範例：**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n }\n}\n```\n\n***\n\n * 步驟 6. 輪詢任務結果\n\n使用任務 ID 查詢狀態：\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.1/task/hair-transfer/ \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * 步驟 7. 取得結果\n\n成功的回應會包含結果圖片的下載網址：\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nAPI Key 無效的錯誤回應：\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n應用案例：\n應用案例：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_style_v1_video_08513beb46.jpg)\n\n拍攝建議：\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/AI_Hair_Extension_recommendation_ba24bd5d92.png)\n\n## 檔案規格與錯誤\n* 支援的格式與尺寸\n\n|AI 功能|支援的尺寸|支援的檔案大小|支援的格式|\n| ---- | ---- | ---- | ---- |\n|AI 虛擬髮型|長邊 <= 1024，臉寬 >= 128，臉部姿勢：-10 < pitch < +10，-45 < yaw < +45，-15 < roll < +15，僅限單張臉部，需呈現完整臉部|< 10MB|jpg/jpeg|\n\n* 錯誤代碼\n\n|錯誤代碼|說明|\n| ---- | ---- |\n|error_no_shoulder\t|來源圖片中肩膀不可見\n|error_large_face_angle\t|上傳圖片的臉部角度過大\n|error_insufficient_landmarks\t|無法在來源圖片偵測足夠的臉部或身體標記點\n|error_hair_too_short\t|輸入的頭髮過短\n|error_face_pose\t|來源圖片的臉部姿勢不受支援\n\n* 環境與相依性\n\n| 範例程式語言 / 工具 | 建議的執行環境版本 |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58（現代 TLS/HTTP 支援）
- jq >= 1.6（穩健的 JSON 解析） |\n| Node.js（JavaScript） | Node >= 18（支援全域 fetch） |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4（現代 TLS/相容性），ext-curl（建議）或 allow_url_fopen=On + ext-openssl、ext-json |\n| Python | Python >= 3.10（支援 f-strings），requests >= 2.20.0 |\n| Java | Java 11+（支援 HttpClient），Jackson Databind >= 2.12.0 |\n\n---\n\n## 常見問題\n**問：我可以試戴自訂的髮型嗎？**\n\n**答：** 完全可以，您可以使用自己的參考照片試戴自訂髮型。AI 虛擬髮型支援兩種指定理想髮型的方法：\n\n1. **上傳您自己的參考圖片**\n 您可以透過 File API（`/s2s/v2.0/file`）上傳高解析度的自拍或風格照片（例如展示目標髮型的人）。上傳後，在建立 AI 任務時，使用回傳的 `file_id` 或公開網址作為參考來源。\n\n2. **提供有效的圖片網址**\n 若您的參考圖片已託管在線上（例如在您自己的伺服器或 CDN 上），您可以直接在請求內容的 `ref_file_url` 欄位提供其 HTTPS 網址。\n\n透過 `/s2s/v2.1/task/hair-transfer` 提交任務時，請包含以下其中之一：\n- `src_file_id`（您的自拍）與 `ref_file_id`（您的自訂參考圖片），\n或\n- `src_file_url` 與 `ref_file_url`。\n\n請確保兩張圖片都符合指定的需求：\n- 支援的格式：僅限 JPG/JPEG\n- 檔案大小低於 10 MB\n- 長邊 ≤ 1024 像素\n- 臉寬 ≥ 128 像素\n- 頭部姿勢在允許範圍內（pitch：−10° 到 +10°，yaw：−45° 到 +45°，roll：−15° 到 +15°）\n- 可見單張臉部，完整正面視角且頭髮清晰可見\n\n這種彈性讓您可以從照片參考套用幾乎任何髮型，而不僅限於預先定義的範本。\n\n---\n\n## 點數消耗\n\n| AI 功能 | 消耗的點數 |\n|---|---|\n| AI 虛擬髮型 V2.0 | 預設模式 1 點
自訂模式 2 點 |\n| AI 虛擬髮型 V2.1 | 預設模式 2 點
自訂模式 2 點 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.216.199"},"lang":"zh-TW","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/zh-tw/reference/ai_hairstyle","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}