Перейти к содержанию

Сравнение лиц

Работа с методами API сравнения лиц#

Warning

Для использования методов необходимо использовать токен авторизации. Методы доступны только при использовании токена. В качестве авторизации используется Auth: HTTPBearer, то есть будет выдан токен UUID4, который нужно будет использовать при использовании описанных выше методов.

API Сравнения лиц включает в себя следующие методы:

  1. Сравнение лиц
  2. Получение конкретного результата сравнения лиц
  3. Получение истории результатов сравнения лиц

1. Сравнение лиц#

Метод POST /v1/events/face_comparison позволяет получить результат сравнения лиц 1 к 1. В запросе поле images (2 изображения) является обязательным и представлено в формате multipart/form-data.

Ограничения:

  1. Метод позволяет отправить только 2 фото
  2. На каждом изображении должно быть только по 1 лицу
  3. Размер лица на изображении должен быть больше 244x224 пикселей

В случае успешного распознавания вернется ответ вида: 

{
  "id": "a716abcd-6f53-4594-976e-c050573eac0f",  // (1)
  "creation_date": "2023-05-25T12:48:05.181414", // (2)
  "type": "comparison",                          // (3)
  "status": "complete",                          // (4)
  "result": [
    {
      "similarity": 0.8618,                      // (5)
      "first_coordinates": {                     // (6)
        "start": [                               
          232,
          201
        ],
        "end": [
          411,
          502
        ]
      },
      "last_coordinates": {                       // (7)
        "start": [
          266,
          192
        ],
        "end": [
          360,
          335
        ]
      }
    }
  ]
}

  1. Идентификационный номер распознвания
  2. Время создания записи
  3. Тип распознавания
  4. Cтатус запроса: complete - успех , failed - ошибка распознавания
  5. Вероятность того, что два лица похожи
  6. Координаты лица первого изображения
  7. Координаты лица второго изображения

При ошибке сравнения, ответ будет выглядеть следующим образом: 

{
  "task_id": "51249bbc-46df-4cf0-8dc2-6a1cf6f66986",
  "creation_date": "2023-05-25T12:48:05.181414", 
  "type": "comparison",                          
  "status": "complete",                          
  "result": {},
  "error": {
    "first_image": {                        //(1)
      "type": "is_not_liveness"                            //(2)
    },
    "last_mage": {                          //(3)
      "type": "is_not_liveness"
    }
  }
}

  1. Информация по первому изображению
  2. Тип ошибки при распознавании: many_faces - в кадре более одного лица, no_face - в кадре лицо не обнаружено, image_quality - проблемы с качеством изображения, is_not_liveness - спуфинг атака, corrupted_image - битый файл
  3. Информация по второму изображению

2. Получение конкретного результата сравнения лиц#

Метод GET /v1/events/face_comparison/{face_comparison_id} выдает ответ ранее полученного сравнения на основе его идентификационного номера{face_comparison_id}. Параметр face_comparison_idявляется обязательным.

  • Если запись переданного идентификационного номера существует, система выдаст ответ данного сравнения. Ответы полностью совпадают с примерами, описанными в п.1 Сравнение лиц.
  • Если запись переданного идентификационного номера отсутствует, система выдаст ошибку с соответствующей информацией.

3. Получение истории результатов сравнения лиц#

Метод GET /v1/events/face_comparison позволяет получить список существующих сравнений в системе. Для отображения (пагинации) результатов используется обязательные параметры limit и offset.

  • limit представляет собой целочисленное значение, определяющее ограничение на количество результатов. По умолчанию установлено значение 50.
  • offset также является целочисленным значением, определяющим смещение для пагинации результатов. Значение по умолчанию - 0.
{
  "limit": 50,
  "offset": 0,
  "total":0,
  "items": [
    {
      "id": "349eb95f-cb90-4703-a95c-0be03229a69c",
      "creation_date": "2023-05-25T09:56:31.862570+00:00",
      "type": "comparison",
      "status": "complete",
      "result": [
        {
          "similarity": 1,
          "first_coordinates": {
            "start": [
              253,
              232
            ],
            "end": [
              668,
              746
            ]
          },
          "last_coordinates": {
            "start": [
              253,
              232
            ],
            "end": [
              668,
              746
            ]
          }
        }
      ]
    },
    {
      "id": "a716abcd-6f53-4594-976e-c050573eac0f",
      "creation_date": "2023-05-25T12:48:05.181414+00:00",
      "type": "comparison",
      "status": "complete",
      "result": [
        {
          "similarity": 0.8618,
          "first_coordinates": {
            "start": [
              232,
              201
            ],
            "end": [
              411,
              502
            ]
          },
          "last_coordinates": {
            "start": [
              266,
              192
            ],
            "end": [
              360,
              335
            ]
          }
        }
      ]
    }
  ]
}