# AI 臉部色彩調分析儀

# 概述
AI 臉部色彩分析偵測臉部膚色，以及眼睛、眉毛、嘴唇與頭髮的顏色。這項包容性的技術為所有族裔確保完整的客製化購物體驗。
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_02_02_enu_21a3d8d423.jpg)
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s5_poster_2_8a8f9307d2.png)
## 整合指南
* 如何為 AI 臉部色彩分析拍攝照片
正面自拍
  - 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。
  - 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。
* 如何用 AI 偵測膚況問題

1. **調整來源圖片尺寸**
調整您的照片以符合支援的尺寸。細節請參考**[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)**
2. **使用 File API 上傳檔案**
使用 ***/s2s/v2.0/file*** API 上傳目標使用者圖片。
  - 圖片需求
    - 細節請參考**
[檔案規格與錯誤](#section/overview/File-Specs-and-Errors)
**。
  - ***重要***：僅呼叫 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 錯誤。
3. **執行 AI 臉部色彩分析任務**
上傳完成後，AI 將使用您的檔案 ID 檢查您嘴唇、眼睛、眉毛、皮膚與頭髮的色調。請參考**[輸入與輸出](#section/overview/Inputs-and-Outputs)**。
接著，使用
檔案 ID 執行增強任務，並取得 ***task_id***。
4. **輪詢以查詢任務狀態直到成功或錯誤**
這個 ***task_id*** 用於透過輪詢 GET 'task/skin-tone-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。
**警告：** 請注意，依據任務的保留期間**輪詢**以查詢任務狀態是強制性的。若在保留期間內沒有輪詢請求，任務將被逾時，即使任務已成功處理（您的點數仍會被消耗）。
> **警告：** 一旦您查詢已逾時任務的狀態，會得到 ***InvalidTaskId*** 錯誤。因此，執行 AI 任務後，您需要在保留期間內**輪詢**以查詢狀態，直到狀態變為 *success* 或 *error*。
5. **成功後取得 AI 任務的結果**
引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。
點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。
扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。

![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg)


---

## 輸入與輸出
* 輸入

AI 會分析您皮膚的色調。您可以調整
`face_angle_strictness_level`
 來控制輸入臉部角度的檢查嚴格程度，範圍從 strict、high、medium、low 到 flexible。嚴格程度適用於臉部角度偵測，包括 pitch、yaw 與 roll。較嚴格的等級可確保更準確的臉部特徵結果。預設設定為 high。

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


```json
{
  "status": 200,
  "data": {
    "task_status": "success",
    "results": {
      "color": {
        "eye_color": "#293F9B",
        "eye_color_name": "Blue",
        "lip_color": "#D23245",
        "eyebrow_color": "#5B2B31",
        "skin_color": "#b9947c",
        "hair_color": "#a0a0a0",
        "hair_color_name": "Auburn"
      }
    }
  }
}
```
| **結果參數** | **結果類型** |
|  --- | --- |
| `skin_color` | 十六進位值 |
| `eye_color` | 十六進位值 |
| `eye_color_name` | 琥珀色、棕色、綠色、藍色、灰色、其他 |
| `lip_color` | 十六進位值 |
| `eyebrow_color` | 十六進位值 |
| `hair_color` | 十六進位值 |
| `color.hair_color_name` | 紅棕色、黑色、金色、棕色、灰白、紅色 |

* 拍攝建議：

![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)

> **警告：** 臉部寬度需大於圖片寬度的 60%。



---

## 檔案規格與錯誤
* 支援的格式與尺寸

| AI 功能 | 支援的尺寸 | 支援的檔案大小 | 支援的格式 |
|  --- | --- | --- | --- |
| AI 臉部色彩分析 | 長邊 <= 4096，僅限單人。邊長超過 1080px 的圖片會自動調整尺寸以進行分析。 | < 10MB | jpg/jpeg/png |

* 錯誤代碼

| 錯誤代碼 | 說明 |
|  --- | --- |
| error_below_min_image_size | 來源圖片尺寸必須至少為 320 像素。 |
| error_face_position_invalid | 臉部必須完全可見、面向前方，並位於圖片中央。 |
| error_face_position_too_small | 偵測到的臉部太小，無法分析。 |
| error_face_position_out_of_boundary | 臉部超出圖片邊界。 |
| error_face_not_forward_facing | 臉部必須正對鏡頭。 |
| error_face_angle_upward | 臉部向上偏轉過多—請稍微低頭。 |
| error_face_angle_downward | 臉部向下偏轉過多—請稍微抬頭。 |
| error_face_angle_leftward | 臉部向左轉轉過多—請稍微向右轉頭。 |
| error_face_angle_rightward | 臉部向右轉過多—請稍微向左轉頭。 |
| error_face_angle_left_tilt | 臉部向左傾斜過多—請輕輕向右傾頭。 |
| error_face_angle_right_tilt | 臉部向右傾斜過多—請輕輕向左傾頭。 |

* 環境與相依性

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



---

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_skin_tone_analysis.yaml)

## V1.0

 - [POST /s2s/v2.0/task/skin-tone-analysis](https://docs.perfectcorp.com/zh-tw/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis/post.md): 這個端點啟動膚色分析流程。您必須提供來源檔案（透過網址或檔案 ID），並可選指定臉部角度的嚴格程度。任務會以非同步方式處理，您可以使用這個回應回傳的 task_id 查詢其狀態。
 - [GET /s2s/v2.0/task/skin-tone-analysis/{task_id}](https://docs.perfectcorp.com/zh-tw/reference/ai_skin_tone_analysis/v1.0/paths/~1s2s~1v2.0~1task~1skin-tone-analysis~1%7Btask_id%7D/get.md)