Описание интеграции 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

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

​Основное использование

​Обработка ошибок

​Пример ответа об ошибке

​Заключение

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

Основное использование

Обработка ошибок

Пример ответа об ошибке

Заключение