# AI 毛躁髮質分析

# 概述
僅用 3 張照片進行 180° 全視角髮絲毛躁度分析
我們的 AI 毛躁髮質分析只需上傳 3 張照片——頭髮的正面、左側與右側視角——即可在數秒內提供精準的髮絲毛躁度分析。
這高效的流程在數秒內提供準確結果，讓企業能依據髮絲毛躁度提供客製化的頭髮解決方案與抗毛躁產品，無需耗時的面對面諮詢、複雜的頭髮測驗，或專用硬體安裝。
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_02_enu_b80c238858.jpg)
## 整合指南
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. **執行 AI 任務以取得任務 ID**
使用 /s2s/v2.0/task/hair-frizziness-detection 執行 AI 任務。對於目標使用者圖片，提供 `src_file_url` 或 `src_file_id`。並提供要套用的 `template_id` 以取得 `task_id`。
2. **輪詢以查詢任務狀態直到成功或失敗**
使用 `task_id`，透過輪詢 GET /s2s/v2.0/task/hair-frizziness-detection 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 running，此階段不會消耗點數。
您也可以實作 webhook，在 AI 任務成功或失敗時接收通知。細節請參考 **[Webhook](../../../../develop/webhook)** 章節。
> **警告：** 必須在任務的保留期間內輪詢以查詢任務狀態。若在保留期間內沒有輪詢請求，任務將會逾時，即使任務已成功處理。您的點數仍會被消耗。
> **警告：** 若您查詢已逾時任務的狀態，會收到 InvalidTaskId 錯誤。因此，執行 AI 任務後，您必須在保留期間內輪詢以查詢狀態，直到狀態變為 success 或 error。
3. **成功後取得 AI 任務的結果**
引擎處理您的輸入檔案並生成結果影像後，任務狀態會變為 success。您會取得處理後圖片的網址。

## 輸入與輸出
* 輸入格式
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_step_01_ac5c651ea4.png)
上傳 3 張照片——頭髮的正面、左側與右側視角。
您可以使用 JS Camera Kit 實作 JavaScript 攝影模組，拍攝 3 張合格的照片。
* 輸出格式
AI 毛躁髮質分析評估髮質類型，並辨識 4 種不同的髮絲毛躁程度——從平滑頭髮到極度毛躁的頭髮，提供關於髮絲毛躁狀況的精準洞察。

| **對應（0–3）** | **術語** | **說明** |
|  --- | --- | --- |
| 0 | 不毛躁 | 頭髮看起來平滑，幾乎或完全沒有可見的毛躁。 |
| 1 | 輕微毛躁 | 可見輕微毛躁；表面質地有輕微的不規則。 |
| 2 | 毛躁 | 頭髮各處有明顯毛躁；質地明顯紊亂。 |
| 3 | 極度毛躁 | 強烈且廣泛的毛躁；頭髮質地高度不規則。 |

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_frizzy_S_01_enu_fcd10905ff.jpg)
* 輸出範例


```json
{
  "mapping": 1, // number；結果對應的鍵，選項：[0, 1, 2, 3]
  "term": "Slightly Frizzy" // string；與 "mapping" 一一對應，選項：["Not Frizzy", "Slightly Frizzy", "Frizzy", "Extreme Frizzy"]
}
```
## 檔案規格與錯誤
* 支援的格式與尺寸

| 類型 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |
|  --- | --- | --- | --- |
| AI 毛躁髮質分析 | 圖片寬與高至少 320 像素，任一維度不超過 4096 像素。若您的圖片其中一邊超過 1080 像素，會自動調整尺寸以符合該限制進行分析。 | < 10MB | jpg/png |

* 錯誤代碼

| 錯誤代碼 | 說明 |
|  --- | --- |
| error_mismatch_image_size | 請確保您所有的臉部照片（正面、左側、右側）尺寸相同 |
| error_below_min_image_size | 若您的圖片寬或高小於 320 像素，尺寸過小無法使用 |
| error_face_position_invalid | 您的臉部必須在圖片中完全可見，不可有任何部分被裁切 |
| error_face_position_too_small | 您照片中的臉部太小，無法妥善分析 |
| error_face_position_out_of_boundary | 您的臉部過大，或部分超出照片邊緣 |
| error_insufficient_lighting | 光線過暗，導致難以分析 |
| error_face_angle_invalid | 您的臉部角度不太正確。正面拍攝時，請讓頭部偏離直線不超過 10 度。側面拍攝時，角度應超過 15 度 |

* 環境與相依性

| 範例程式語言 / 工具 | 建議的執行環境版本 |
|  --- | --- |
| 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 | 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_hair_frizziness_detection.yaml)

## V1.0

 - [POST /s2s/v2.0/task/hair-frizziness-detection](https://docs.perfectcorp.com/zh-tw/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection/post.md): 查詢任務狀態請參考輪詢指南。
 - [GET /s2s/v2.0/task/hair-frizziness-detection/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_hair_frizziness_detection/v1.0/paths/~1s2s~1v2.0~1task~1hair-frizziness-detection~1%7Btask_id%7D/get.md)