> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 五官定位 API 対接説明
> Face Transformation 集成指南 - XHuoAPI
本文では、五官定位 API 対接説明を紹介します。これは、画像を入力することで、リクエストされた画像の五官を定位（顔のキーポイント定位とも呼ばれる）し、顔の輪郭を構成する90のポイントを計算します。これには、眉毛（左右それぞれ8ポイント）、目（左右それぞれ8ポイント）、鼻（13ポイント）、口（22ポイント）、顔の輪郭（21ポイント）、眼球\[または瞳孔]（2ポイント）が含まれます。
## 申請プロセス
APIを使用するには、まず[五官定位 API](https://api.xhuoapi.ai/documents/20945baf-b263-457b-be5f-0332c2180a57)の該当ページでサービスを申請する必要があります。ページに入ったら、「Acquire」ボタンをクリックします。以下の図のように：
まだログインまたは登録していない場合は、自動的にログインページにリダイレクトされ、登録とログインを促されます。ログインまたは登録後、現在のページに自動的に戻ります。
初回申請時には無料のクレジットが付与され、このAPIを無料で使用できます。
## 基本的な使用法
まず、基本的な使用方法を理解します。画像リンクを入力するだけで、処理後の結果画像を得ることができます。まず、`image_url`フィールドを簡単に渡す必要があります。顔の画像は以下の図のように：
次に、画面上に対応する内容を記入できます。以下の図のように：
ここでは、Request Headersを設定しました。これには以下が含まれます：
* `accept`：受け取りたいレスポンス結果の形式。ここでは`application/json`、すなわちJSON形式を記入します。
* `authorization`：APIを呼び出すためのキー。申請後、直接ドロップダウンから選択できます。
さらに、Request Bodyを設定しました。これには以下が含まれます：
* `image_url`：処理する顔の画像リンク。
* `mode`：検出モード。0はすべての顔を検出し、1は面積が最大の顔を検出します。デフォルトは0です。
* `face_model_version`：顔認識サービスで使用されるアルゴリズムモデルのバージョン。デフォルトは`3.0`です。
* `need_rotate_detection`：画像の回転認識サポートを有効にするかどうか。0は無効、1は有効。デフォルトは0です。
選択後、右側にも対応するコードが生成されていることがわかります。以下の図のように：
「Try」ボタンをクリックするとテストを行うことができます。上の図のように、ここで以下の結果を得ました：
```json theme={null}
{
"image_width": 690,
"image_height": 920,
"face_model_version": "3.0",
"face_shape_set": [
{
"face_profile": [
{
"x": 294,
"y": 207
},
{
"x": 289,
"y": 216
},
{
"x": 286,
"y": 226
},
{
"x": 284,
"y": 236
},
{
"x": 283,
"y": 246
},
{
"x": 283,
"y": 256
},
{
"x": 284,
"y": 266
},
{
"x": 286,
"y": 276
},
{
"x": 289,
"y": 285
},
{
"x": 294,
"y": 294
},
{
"x": 301,
"y": 301
},
{
"x": 314,
"y": 306
},
{
"x": 327,
"y": 307
},
{
"x": 340,
"y": 306
},
{
"x": 353,
"y": 302
},
{
"x": 365,
"y": 296
},
{
"x": 374,
"y": 287
},
{
"x": 382,
"y": 276
},
{
"x": 387,
"y": 264
},
{
"x": 392,
"y": 251
},
{
"x": 396,
"y": 238
}
],
"left_eye": [
{
"x": 298,
"y": 208
},
{
"x": 301,
"y": 212
},
{
"x": 305,
"y": 214
},
{
"x": 309,
"y": 215
},
{
"x": 314,
"y": 216
},
{
"x": 313,
"y": 210
},
{
"x": 309,
"y": 207
},
{
"x": 303,
"y": 206
}
],
"right_eye": [
{
"x": 363,
"y": 229
},
{
"x": 358,
"y": 230
},
{
"x": 353,
"y": 229
},
{
"x": 347,
"y": 227
},
{
"x": 342,
"y": 224
},
{
"x": 348,
"y": 221
},
{
"x": 354,
"y": 221
},
{
"x": 360,
"y": 223
}
],
"left_eye_brow": [
{
"x": 296,
"y": 196
},
{
"x": 302,
"y": 197
},
{
"x": 308,
"y": 198
},
{
"x": 313,
"y": 200
},
{
"x": 319,
"y": 202
},
{
"x": 315,
"y": 195
},
{
"x": 309,
"y": 192
},
{
"x": 302,
"y": 192
}
],
"right_eye_brow": [
{
"x": 377,
"y": 221
},
{
"x": 369,
"y": 217
},
{
"x": 360,
"y": 213
},
{
"x": 350,
"y": 211
},
{
"x": 341,
"y": 208
},
{
"x": 351,
"y": 204
},
{
"x": 362,
"y": 206
},
{
"x": 372,
"y": 211
}
],
"mouth": [
{
"x": 296,
"y": 262
},
{
"x": 297,
"y": 269
},
{
"x": 299,
"y": 276
},
{
"x": 305,
"y": 281
},
{
"x": 315,
"y": 283
},
{
"x": 326,
"y": 282
},
{
"x": 335,
"y": 277
},
{
"x": 325,
"y": 269
},
{
"x": 315,
"y": 262
},
{
"x": 309,
"y": 261
},
{
"x": 305,
"y": 258
},
{
"x": 300,
"y": 259
},
{
"x": 299,
"y": 265
},
{
"x": 303,
"y": 269
},
{
"x": 307,
"y": 272
},
{
"x": 316,
"y": 275
},
{
"x": 325,
"y": 276
},
{
"x": 326,
"y": 272
},
{
"x": 317,
"y": 269
},
{
"x": 308,
"y": 265
},
{
"x": 304,
"y": 263
},
{
"x": 300,
"y": 262
}
],
"nose": [
{
"x": 311,
"y": 242
},
{
"x": 325,
"y": 220
},
{
"x": 319,
"y": 226
},
{
"x": 313,
"y": 231
},
{
"x": 307,
"y": 236
},
{
"x": 302,
"y": 243
},
{
"x": 306,
"y": 249
},
{
"x": 311,
"y": 252
},
{
"x": 318,
"y": 254
},
{
"x": 329,
"y": 253
},
{
"x": 327,
"y": 243
},
{
"x": 326,
"y": 235
},
{
"x": 326,
"y": 228
}
],
"left_pupil": [
{
"x": 310,
"y": 211
}
],
"right_pupil": [
{
"x": 357,
"y": 225
}
]
}
]
}
```
この時点で、画像中の顔に関する情報、顔の特徴点（顔のキーポイント）の具体的な情報、顔認識に使用されるアルゴリズムモデルのバージョンなどが得られました。
フィールドの説明は以下の通りです：
* `image_width` ：要求された画像の幅。
* `image_height` ：要求された画像の高さ。
* `face_model_version`：顔認識に使用されるアルゴリズムモデルのバージョン。
* `face_shape_set`：五官の位置（顔の重要点）の具体的な情報。
* `face_profile` ：顔の輪郭を表す21点。
* `x` ：x座標
* `y` ：y座標
* `left_eye` ：左側の目の輪郭を表す8点。
* `x` ：x座標
* `y` ：y座標
* `right_eye ` ：右側の目の輪郭を表す8点。
* `x` ：x座標
* `y` ：y座標
* `left_eye_brow` ：左側の眉毛の輪郭を表す8点。
* `x` ：x座標
* `y` ：y座標
* `right_eye_brow ` ：右側の眉毛の輪郭を表す8点。
* `x` ：x座標
* `y` ：y座標
* `mouth` ：口の輪郭を表す22点。
* `x` ：x座標
* `y` ：y座標
* `nose` ：鼻の輪郭を表す13点。
* `x` ：x座標
* `y` ：y座標
* `left_pupil` ：左瞳孔の輪郭を表す1点。
* `x` ：x座標
* `y` ：y座標
* `right_pupil` ：右瞳孔の輪郭を表す1点。
* `x` ：x座標
* `y` ：y座標
また、対応する接続コードを生成したい場合は、生成されたものを直接コピーできます。例えば、CURLのコードは以下の通りです：
```shell theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/face/analyze' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
"image_url": "https://cdn.xhuoapi.ai/lrbtcn.jpg"
}'
```
Pythonの接続コードは以下の通りです：
```python theme={null}
import requests
url = "https://api.xhuoapi.ai/v1/face/analyze"
headers = {
"accept": "application/json",
"authorization": "Bearer {token}",
"content-type": "application/json"
}
payload = {
"image_url": "https://cdn.xhuoapi.ai/lrbtcn.jpg"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)
```
## エラーハンドリング
APIを呼び出す際にエラーが発生した場合、APIは対応するエラーコードと情報を返します。例えば：
* `400 token_mismatched`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `400 api_not_implemented`：不正なリクエスト、パラメータが不足しているか無効である可能性があります。
* `401 invalid_token`：認証されていない、無効または不足している認証トークン。
* `429 too_many_requests`：リクエストが多すぎます、レート制限を超えました。
* `500 api_error`：内部サーバーエラー、サーバーで何かがうまくいきませんでした。
### エラー応答の例
```json theme={null}
{
"success": false,
"error": {
"code": "api_error",
"message": "fetch failed"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 結論
この文書を通じて、五官位置APIを使用して入力画像の五官位置を特定する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。