AI 臉部色彩調分析儀
如何為 AI 臉部色彩分析拍攝照片
正面自拍
- 只需一張清晰的照片，直視鏡頭。讓頭髮放下垂於胸前，並確保直視前方，取得正面視角。
- 或者，使用 JS Camera Kit 拍照。只需讓頭髮放下垂於胸前，不要綁起。
如何用 AI 偵測膚況問題
調整來源圖片尺寸
調整您的照片以符合支援的尺寸。細節請參考**檔案規格與錯誤**使用 File API 上傳檔案
使用 /s2s/v2.0/file API 上傳目標使用者圖片。圖片需求
- 細節請參考**檔案規格與錯誤**。
重要：僅呼叫 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 錯誤。
執行 AI 臉部色彩分析任務
上傳完成後，AI 將使用您的檔案 ID 檢查您嘴唇、眼睛、眉毛、皮膚與頭髮的色調。請參考**輸入與輸出**。
接著，使用 檔案 ID 執行增強任務，並取得 task_id。輪詢以查詢任務狀態直到成功或錯誤
這個 task_id 用於透過輪詢 GET 'task/skin-tone-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。警告： 請注意，依據任務的保留期間輪詢以查詢任務狀態是強制性的。若在保留期間內沒有輪詢請求，任務將被逾時，即使任務已成功處理（您的點數仍會被消耗）。
警告： 一旦您查詢已逾時任務的狀態，會得到 InvalidTaskId 錯誤。因此，執行 AI 任務後，您需要在保留期間內輪詢以查詢狀態，直到狀態變為 success 或 error。
成功後取得 AI 任務的結果
引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。 點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。
扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。
- 輸入 AI 會分析您皮膚的色調。您可以調整
face_angle_strictness_level來控制輸入臉部角度的檢查嚴格程度，範圍從 strict、high、medium、low 到 flexible。嚴格程度適用於臉部角度偵測，包括 pitch、yaw 與 roll。較嚴格的等級可確保更準確的臉部特徵結果。預設設定為 high。
- 輸出
{
"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 | 紅棕色、黑色、金色、棕色、灰白、紅色 |
- 拍攝建議：
警告： 臉部寬度需大於圖片寬度的 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 |