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 臉部特徵與比例偵測任務
上傳完成後，您可以使用檔案 ID 選擇多個要分析的臉部特徵。請參考**輸入與輸出**。
接著，使用 檔案 ID 執行增強任務，並取得 task_id。輪詢以查詢任務狀態直到成功或錯誤
這個 task_id 用於透過輪詢 GET 'task/face-attr-analysis' 監控任務狀態，以取得目前的引擎狀態。在引擎完成任務之前，狀態會維持為 'running'，此階段不會消耗點數。警告： 請注意，依據任務的保留期間輪詢以查詢任務狀態是強制性的。若在保留期間內沒有輪詢請求，任務將被逾時，即使任務已成功處理（您的點數仍會被消耗）。
警告： 一旦您查詢已逾時任務的狀態，會得到 InvalidTaskId 錯誤。因此，執行 AI 任務後，您需要在保留期間內輪詢以查詢狀態，直到狀態變為 success 或 error。
成功後取得 AI 任務的結果
引擎成功處理您的輸入檔案並生成結果影像後，任務會變為 'success' 狀態。您會取得處理後影像的網址，以及一個 dst_id，讓您在無需重新上傳結果圖片的情況下串接另一個 AI 任務。 點數僅在這種情況下會被消耗。若引擎處理任務失敗，任務狀態會變為 'error'，且不會消耗點數。
扣除點數時，系統會優先使用接近到期的點數。若到期日相同，則扣除最早取得的點數。
- 實際範例：
- 臉部特徵：
| 類別 | 子類別 | 請求參數 | 結果參數 | 結果類型 |
|---|---|---|---|---|
| 臉 | 臉型 | faceShape | faceshape | 三角形、菱形、心形、倒三角形、長形、橢圓形、圓形、方形、未知 |
| 年齡與性別 | 年齡 | age | agegender.age | 整數 |
| 性別 | gender | agegender.gender | female、male、unknown | |
| 眼睛 | 眼型 | eyeShape | eyelid.left_shape、eyelid.right_shape | 窄、圓、杏仁 |
| 眼睛大小 | eyeSize | eyelid.size | 大、小、平均 | |
| 眼睛角度 | eyeAngle | eyelid.left_angle、eyelid.right_angle | 下垂、上揚、平均 | |
| 眼睛距離 | eyeDistance | eyelid.setting | 靠近、分開、平均 | |
| 眼皮 | eyelid | eyelid.left_eyelid、eyelid.right_eyelid | 遮眼型、單眼皮、雙眼皮、深邃型 | |
| 眉毛 | 眉型 | eyebrowShape | eyebrow.left_shape、eyebrow.right_shape | 硬角、柔角、平直、圓弧、不明顯 |
| 眉毛厚度 | eyebrowThickness | eyebrow.left_body_thickness、eyebrow.right_body_thickness | 濃密、稀疏、平均、未知 | |
| 眉毛距離 | eyebrowDistance | eyebrow.gap | 分開、靠近、平均 | |
| 眉毛長度 | eyebrowShortness | eyebrow.left_shortness、eyebrow.right_shortness | 短、正常 | |
| 嘴唇 | 唇型 | lipShape | lipshape[] | 弓形、下垂、飽滿、下唇厚、上唇厚、窄、圓、薄、寬、平均 |
| 鼻子 | 鼻寬 | noseWidth | nose.width | 窄、寬、平均 |
| 鼻長 | noseLength | nose.length | 長、短、平均 | |
| 顴骨 | 顴骨 | cheekbones | cheekbone.left、cheekbone.right、cheekbone.overall | 平坦顴骨、高顴骨、低顴骨、圓臉頰 |
- 臉部比例：
| 子類別 | 請求參數 | 結果參數 | 結果類型 | 說明 |
|---|---|---|---|---|
| 水平三等分比例 | horizontalThird | horizontal_third | 三段百分比；解讀：短／均衡／長；黃金比例：33% : 33% : 33% | 臉部水平比例基於將臉部分為三個等分：從髮際線到眉毛下緣、從眉毛下緣到鼻子下緣、從鼻子下緣到下巴尖端。三者之間的黃金比例（理想比例）為 1:1:1。 |
| 垂直五等分比例 | verticalFifth | vertical_fifth | 五段百分比；解讀（眼距與眼寬）：窄／均衡／寬；黃金比例：20% : 20% : 20% : 20% : 20% | 臉部垂直比例由將臉部分為五個區塊決定：一隻眼睛的寬度、兩眼之間的距離，以及從眼睛外角到臉部邊緣的間距。這些比例的黃金比例為 1:1:1:1:1。 |
| 臉部長寬比 | faceAspectRatio | face_aspect_ratio | [1, r]；解讀：短／均衡／長；黃金比例：1 : 1.46 | 臉部長寬比是臉部寬度與高度的關係，理想上遵循 1:1.46 的黃金比例，創造均衡且具美感的視覺。 |
| 眼睛長寬比 | eyeAspectRatio | left_eye_aspect_ratio right_eye_aspect_ratio | [1, r]；解讀：圓／均衡／平；黃金比例：1 : 3 | 眼睛長寬比是眼睛高度與寬度的關係，理想上符合 1:3 的黃金比例，確保最具美感的均衡視覺。 |
| 眉峰比例 | eyebrowArch | left_eyebrow_arch_to_eyebrow_width right_eyebrow_arch_to_eyebrow_width | [1, r]；解讀：短眉峰／均衡／長眉峰；黃金比例：1 : 1.618 | 眉峰的理想比例取決於眉毛本身的形狀，其最高點（眉峰）符合黃金比例，創造具美感的視覺。 |
| 眼高到眉毛距離 | eyeHeightToEyebrowDistance | left_eye_height_to_eyebrow_distance right_eye_height_to_eyebrow_distance overall_eye_height_to_eyebrow_distance | [1, r]；解讀：短／均衡／長；黃金比例：1 : 1.618 | 眼到眉距離是從上眼皮頂部到眉毛最高點的垂直距離。理想上，與眼高相比遵循 1.618:1 的黃金比例，達到眼睛與眉毛之間最和諧的平衡。 |
| 鼻子長寬比 | noseAspectRatio | nose_aspect_ratio | [1, r]；解讀：寬／均衡／窄；黃金比例：1 : 1.618 | 鼻子長寬比是鼻子寬度與高度的關係，理想上遵循 1:1.618 的黃金比例。 |
| 鼻寬到嘴寬 | noseWidthToMouthWidth | nose_width_to_mouth_width | [1, r]；解讀：小／均衡／大；黃金比例：1 : 1.618 | 鼻寬到嘴寬比例是鼻子寬度與嘴巴寬度的關係，理想上遵循 1:1.618 的黃金比例，創造均衡且具美感的視覺。 |
| 鼻到唇到下巴 | noseToLipToChin | nose_to_lip_to_chin | [1, r]；解讀：短／均衡／長（下臉長度）；黃金比例：1 : 1.618 | 鼻到唇到下巴比例是指從鼻底到唇中心的距離為 1，唇中心到下巴的理想距離為 1.618。這個黃金比例遵循臉部對稱原則，創造均衡和諧的下臉。 |
| 上唇到下唇 | upperLipToLowerLip | upper_lip_to_lower_lip | [1, r]；解讀：上唇飽滿／均衡／下唇飽滿；黃金比例：1 : 1.618 | 上唇到下唇的黃金比例意指下唇厚度應為上唇的 1.618 倍。這個比例創造均衡且具美感的視覺，下唇略為飽滿於上唇。 |
- 拍攝建議：
警告： 臉部寬度需大於圖片寬度的 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 |