# 顔の比率分析

# 概要
顔の比率分析では、顔の構造を解析し、顔、目、眉、唇、鼻、頬骨などの形状を特定します。

## 統合ガイド
* 顔の比率分析 用に写真を撮る方法

* 正面を向いた自撮り写真を撮る
  - 鮮明な写真 1 枚で、カメラにまっすぐ向き合ってください。髪は自然な状態にし、顔全体が隠れることなく見える状態がベストです。おでこを出すために髪を流し、まっすぐ正面を見つめることで、適切な正面からのアングルを撮影してください。
  - または、JS Camera Kit を使用して写真を撮影してください。自動的な顔アラインメント、ライティングのガイド、顔サイズ検出に従い、写真が処理に必要な基準を満たすことを確認してください。

* AI による肌の悩みの検出方法

1. **ソース画像のサイズを変更する**</br>
   写真のサイズをサポートされている寸法に合わせてください。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)**

2. **File API を使用してファイルをアップロードする**</br>
   ***/s2s/v2.0/file*** API を使用して、対象のユーザー画像をアップロードします。
     - 画像の要件
       - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** をご覧ください。
     ***重要***: File API を呼び出すだけでは、ファイルはアップロードされません。File API レスポンスで提供された **URL** へファイルを **手動でアップロード** する必要があります。その URL がアップロード先です。続行する前に、ファイルがそこに正常に転送されたことを確認してください。<br>
     AI API を呼び出す前に、ファイルが正常にアップロード済みであることを確認してください。File API を使用してアップロード用 URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスで ***file_id*** を受け取ります。この ID を使用して、そのファイルに関連する AI 機能にアクセスします。

      > **警告:** File API レスポンスで提供された URL へファイルをアップロードせずに AI API を使用すると、500 Server Error / unknown_internal_error または 404 Not Found のエラーが発生する点にご注意ください。

3. **顔の比率分析 タスクを実行する**</br>
   アップロードが完了すると、ファイル ID を使用して分析する複数の顔属性を選択できます。 **[入力と出力](#section/overview/Inputs-and-Outputs)** を参照してください。</br>
   その後、File ID を用いて POST 'task/face-attr-analysis' を呼び出すと、
   enhance タスクが実行され、***task_id*** が取得されます。

4. **タスクが成功またはエラーになるまでポーリングでステータスを確認する**</BR>
この ***task_id*** を使用して、GET 'task/face-attr-analysis' をポーリングし、現在のエンジンステータスを取得してタスクのステータスを監視します。エンジンがタスクを完了するまで、ステータスは 'running' のままで、この段階ではユニットは消費されません。

    **警告:** タスクの保持期間に基づいて **ポーリング** でタスクのステータスを確認することは必須です。保持期間内にポーリングリクエストがなければ、タスクが正常に処理されていても、タスクはタイムアウトします（ユニットは消費されます）。

    > **警告:** タイムアウトしたタスクのステータスを確認すると、***InvalidTaskId*** エラーが発生します。そのため、AI タスクを実行したら、保持期間内に **ポーリング** でステータスを確認し、ステータスが *success* または *error* になるまで続行する必要があります。

5. **AI タスクが成功したら結果を取得する**</BR>
エンジンが入力ファイルを正常に処理し、結果画像を生成すると、タスクは 'success' ステータスに変更されます。処理された画像の URL と、結果画像を再アップロードせずに別の AI タスクを連続実行できる dst_id を受け取ります。
ユニットは、この場合にのみ消費されます。エンジンがタスクの処理に失敗すると、タスクのステータスは 'error' に変更され、ユニットは消費されません。</BR>
ユニットを控除する際、システムは期限の近づいているものを優先します。期限が同じ場合は、最も早く取得したユニットを控除します。

* 実際の使用例:
![](https://plugins-media.makeupar.com/smb/blog/post/2025-01-15/10a4b980-f571-4d08-8f5d-e3ed48db77aa.jpg)
## 入力と出力
* 顔属性:
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_01_enu_79380baa14.jpg)

| **カテゴリ**     | **サブカテゴリ**   | **リクエストパラメータ** | **結果パラメータ** | **結果タイプ** |
| --- | --- | --- |  --- | --- |
| **顔** | 顔の形 | `faceShape` | `faceshape` | Triangle, Diamond, Heart, InvTriangle, Oblong, Oval, Round, Square, Unknown |
| **年齢と性別** | 年齢 | `age` | `agegender.age` | integer |
| | 性別 | `gender` | `agegender.gender` | female, male, unknown |
| **目** | 目の形 | `eyeShape` | `eyelid.left_shape`, `eyelid.right_shape` | Narrow, Round, Almond |
| | 目の大きさ | `eyeSize` | `eyelid.size` | Big, Small, Average |
| | 目の角度 | `eyeAngle` | `eyelid.left_angle`, `eyelid.right_angle` | Downturned, Upturned, Average |
| | 目の間隔 | `eyeDistance` | `eyelid.setting` | Close-set, Wide-Set, Average |
| | まぶた | `eyelid` | `eyelid.left_eyelid`, `eyelid.right_eyelid` | Hooded-lid, Single-lid, Double-lid, Deep-Set |
| **眉** | 眉の形 | `eyebrowShape` | `eyebrow.left_shape`, `eyebrow.right_shape` | Hard Angled, Soft Angled, Straight, Rounded, Obscured |
| | 眉の太さ | `eyebrowThickness` | `eyebrow.left_body_thickness`, `eyebrow.right_body_thickness` | Dense, Sparse, Average, Unknown |
| | 眉間 | `eyebrowDistance` | `eyebrow.gap` | Far-Apart, Close, Average |
| | 眉の短さ | `eyebrowShortness` | `eyebrow.left_shortness`, `eyebrow.right_shortness` | Short, Normal |
| **唇** | 唇の形 | `lipShape` | `lipshape[]` | Bow, Downturned, Full, Heavy Lower Lip, Heavy Upper Lip, Narrow, Round, Thin, Wide, Average |
| **鼻** | 鼻の幅 | `noseWidth` | `nose.width` | Narrow, Broad, Average |
| | 鼻の長さ | `noseLength` | `nose.length` | Long, Short, Average |
| **頬骨**   | 頬骨 | `cheekbones` | `cheekbone.left`, `cheekbone.right`, `cheekbone.overall` | Flat Cheekbone, High Cheekbone, Low Cheekbone, Round Cheeks |


---

* 顔比率:
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_01_03_2fe8f06b92.jpg)

| **サブカテゴリ** | **リクエストパラメータ** | **結果パラメータ** | **結果タイプ** | **説明** |
| --- | --- | --- | --- | --- |
| 水平 3 分割比率 | `horizontalThird` | `horizontal_third` | 3 分割のパーセンテージ; 解釈: Short / Balanced / Long; ゴールデンRatio: 33% : 33% : 33% | 顔の水平比率は、顔を 3 つの等しい区間に分割することに基づいています：生え際から眉の下端まで、眉の下端から鼻の下端まで、そして鼻の下端から顎先まで。3 つの区間のゴールデンRatio、つまり理想の比率は 1:1:1 です。|
| 垂直 5 分割比率 | `verticalFifth` | `vertical_fifth` | 5 分割のパーセンテージ; 解釈 (目の間隔と目の幅): Narrow / Balanced / Wide; ゴールデンRatio: 20% : 20% : 20% : 20% : 20% | 顔の垂直比率は、顔を 5 つの区間に分割して決定されます：1 つの目の幅、2 つの目の間隔、そして目の外側から顔の縁までの空間。これらの比率のゴールデンRatioは 1:1:1:1:1 です。 |
| 顔のアスペクト比 | `faceAspectRatio` | `face_aspect_ratio` | `[1, r]`; 解釈: Short / Balanced / Long; ゴールデンRatio: 1 : 1.46 | 顔のアスペクト比は、顔の幅と高さの関係であり、ゴールデンRatio 1:1.46 に従うことが理想です。 |
| 目のアスペクト比 | `eyeAspectRatio` | `left_eye_aspect_ratio` `right_eye_aspect_ratio` | `[1, r]`; 解釈: Round / Balanced / Flat; ゴールデンRatio: 1 : 3 | 目のアスペクト比は、目の高さとその幅の関係であり、ゴールデンRatio 1:3 に合うことが理想です。
 |
| 眉山アーチ比率 | `eyebrowArch` | `left_eyebrow_arch_to_eyebrow_width` `right_eyebrow_arch_to_eyebrow_width` | `[1, r]`; 解釈: Short Arch / Balanced / Long Arch; ゴールデンRatio: 1 : 1.618 | 眉山アーチの理想の比率は、眉自体の形によって決まり、最高点（アーチ）がゴールデンRatio に合致することで、美しい外観が得られます。 |
| 目の高さから眉までの距離 | `eyeHeightToEyebrowDistance` | `left_eye_height_to_eyebrow_distance` `right_eye_height_to_eyebrow_distance` `overall_eye_height_to_eyebrow_distance` | `[1, r]`; 解釈: Short / Balanced / Long; ゴールデンRatio: 1 : 1.618 | 眉までの距離は、上まぶたの上端から眉の最高点までの垂直距離です。理想としては、目の高さを基準にゴールデンRatio 1.618:1 となることで、目と眉の間に最も調和のとれたバランスが得られます。 |
| 鼻のアスペクト比 | `noseAspectRatio` | `nose_aspect_ratio` | `[1, r]`; 解釈: Wide / Balanced / Narrow; ゴールデンRatio: 1 : 1.618 | 鼻のアスペクト比は、鼻の幅と高さの関係であり、ゴールデンRatio 1:1.618 に従うことが理想です。 |
| 鼻幅に対する口幅 | `noseWidthToMouthWidth` | `nose_width_to_mouth_width` | `[1, r]`; 解釈: Small / Balanced / Large; ゴールデンRatio: 1 : 1.618 | 鼻幅と口幅の比率は、鼻の幅と口の幅の関係であり、ゴールデンRatio 1:1.618 に従うことが理想です。 |
| 鼻から唇、顎まで | `noseToLipToChin` | `nose_to_lip_to_chin` | `[1, r]`; 解釈: Short / Balanced / Long (顔の下半分の長さ); ゴールデンRatio: 1 : 1.618 | 鼻から唇、顎までの比率は、鼻の基部から唇の中心までの距離を 1 としたとき、唇の中心から顎までの理想の距離が 1.618 となる比率です。このゴールデンRatioにより、顔の対称性の原理に従い、調和のとれた下半顔が得られます。 |
| 上唇に対する下唇 | `upperLipToLowerLip` | `upper_lip_to_lower_lip` | `[1, r]`; 解釈: Full Upper / Balanced / Full Lower; ゴールデンRatio: 1 : 1.618 | 上唇と下唇のゴールデンRatioでは、下唇の厚さは上唇の 1.618 倍であるべきとされています。この比率により、下唇が上唇よりややふっくらします。 |

----

* 撮影方法の提案:
![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI_Face_Analysis_how_to_shoot_35ca9af08e.png)

> **警告:** 顔の幅は、画像の幅の 60% を超える必要があります。

## ファイル仕様とエラー
* 対応形式と解像度

|AI 機能|対応解像度|対応ファイルサイズ|対応形式|
|  ----  | ----  | ----  | ----  |
|顔の比率分析|長辺 <= 4096、1 人のみ。1 辺が 1080px 超の画像は自動的にリサイズされて分析されます。|< 10MB|jpg/jpeg|

* エラーコード

|エラーコード|説明|
|  ----  | ----  |
| 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</br>   - curl >= 7.58 (最新の TLS/HTTP 対応)</br>   - jq >= 1.6 (堅牢な JSON パース) |
| Node.js (JavaScript) | Node >= 18 (グローバル fetch 用) |
| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - 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 カメラキット
{% partial file="/_partials/js-camera-kit.md" /%}

---

## ユニット消費

* 顔属性・比率分析

| AI 機能 | 消費ユニット数 |
|---|---|
| 顔構造機能 1~5 個 | 10 |
| 顔構造機能 6~14 個 | 20 |
| 顔構造機能 15~28 個 | 30 |

---


License: Privacy policy

## Servers

```
https://yce-api-01.makeupar.com
```

## Security

### BearerAuthenticationV2

[object Object]

Type: http
Scheme: bearer

## Download OpenAPI description

 - [顔の比率分析](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_face_analyzer.yaml)

## V1.0

 - [POST /s2s/v2.0/task/face-attr-analysis](https://docs.perfectcorp.com/ja/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis/post.md): このエンドポイントは、顔属性分析プロセスを開始します。ソースファイル（URL またはファイル ID 経由）を提供し、分析する機能を指定する必要があります。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。
 - [GET /s2s/v2.0/task/face-attr-analysis/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_face_analyzer/v1.0/paths/~1s2s~1v2.0~1task~1face-attr-analysis~1%7Btask_id%7D/get.md)