五官定位 API 対接説明

本文では、五官定位 API 対接説明を紹介します。これは、画像を入力することで、リクエストされた画像の五官を定位（顔のキーポイント定位とも呼ばれる）し、顔の輪郭を構成する90のポイントを計算します。これには、眉毛（左右それぞれ8ポイント）、目（左右それぞれ8ポイント）、鼻（13ポイント）、口（22ポイント）、顔の輪郭（21ポイント）、眼球[または瞳孔]（2ポイント）が含まれます。

申請プロセス

APIを使用するには、まず五官定位 APIの該当ページでサービスを申請する必要があります。ページに入ったら、「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」ボタンをクリックするとテストを行うことができます。上の図のように、ここで以下の結果を得ました：

{
  "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のコードは以下の通りです：

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の接続コードは以下の通りです：

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：内部サーバーエラー、サーバーで何かがうまくいきませんでした。

エラー応答の例

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

結論

この文書を通じて、五官位置APIを使用して入力画像の五官位置を特定する方法を理解しました。この文書がAPIの接続と使用に役立つことを願っています。ご不明な点がございましたら、いつでも技術サポートチームにお問い合わせください。

Documentation Index

​申請プロセス

​基本的な使用法

​エラーハンドリング

​エラー応答の例

​結論

申請プロセス

基本的な使用法

エラーハンドリング

エラー応答の例

結論