API інтеграція для визначення рис обличчя

У цьому документі буде представлено API інтеграцію для визначення рис обличчя, яка може за допомогою введення зображення виконати визначення рис обличчя (також відоме як визначення ключових точок обличчя), обчислюючи 90 точок, що формують контур обличчя, включаючи брови (по 8 точок з кожного боку), очі (по 8 точок з кожного боку), ніс (13 точок), рот (22 точки), контур обличчя (21 точка), зіниці [або зорові яблука] (2 точки).

Процес подачі заявки

Щоб використовувати API, спочатку потрібно перейти на відповідну сторінку API для визначення рис обличчя для подачі заявки на відповідну послугу, після переходу на сторінку натисніть кнопку «Acquire», як показано на малюнку:

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти, після входу або реєстрації ви автоматично повернетеся на поточну сторінку. При першій подачі заявки буде надано безкоштовний ліміт, який дозволяє безкоштовно використовувати цей API.

Основне використання

Спочатку потрібно ознайомитися з основним способом використання, а саме, введенням посилання на зображення, щоб отримати оброблене зображення. Спочатку потрібно просто передати поле image_url, зображення обличчя показано на малюнку нижче:

Далі ми можемо заповнити відповідні дані на інтерфейсі, як показано на малюнку:

Ми можемо бачити, що тут ми налаштували заголовки запиту, включаючи:

accept: який формат відповіді ви хочете отримати, тут вказано application/json, тобто формат JSON.
authorization: ключ для виклику API, після подачі заявки можна вибрати безпосередньо зі списку.

Крім того, налаштовано тіло запиту, яке включає:

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

​Процес подачі заявки

​Основне використання

​Обробка помилок

​Приклад відповіді на помилку

​Висновок

Процес подачі заявки

Основне використання

Обробка помилок

Приклад відповіді на помилку

Висновок