Прямые API-запросы к `findface-extraction-api`

Вы можете использовать HTTP API для извлечения данных напрямую из компонента findface-extraction-api.

Примечание

Будучи аналогом компонента findface-sf-api в том, что касается извлечения данных через API, компонент findface-extraction-api является более ресурсоемким. Данный компонент не может служить полноценной заменой findface-sf-api, поскольку не позволяет добавлять лица и работать с базой данных.

Совет

Нормализованные изображения, полученные с помощью компонента findface-extraction-api, подходят для обработки в компоненте findface-sf-api.

В этом разделе:

API-запросы
Формат API-ответа
Примеры

API-запросы 

Компонент findface-extraction-api принимает POST-запросы по адресу http://127.0.0.1:18666/.

Существует 2 способа настроить формат тела запроса:

application/json: тело запроса целиком состоит из данных в формате JSON.
multipart/form-data: тело запроса включает в себя часть в формате JSON, содержащую собственно запрос, остальные части тела используются для передачи изображения.

Часть в формате JSON тела запроса представляет собой набор запросов:

{
    "requests": [request1, request2, .., requestN]
    "include_timings": true|false // include face processing timing in response, false by default
}

Каждый запрос в наборе имеет отношение к определенному изображению или области на изображении и принимает следующие параметры:

Важно

Чтобы включить распознавание атрибутов лица, можно использовать как новые (предпочтительно), так и старые параметры API. Старый API позволяет распознавать пол, возраст и эмоции, в то время как новый API обеспечивает распознавание пола, возраста, эмоций, страны, бороды и очков. Каждый атрибут лица (пол, возраст, эмоции, страна, борода или очки) может быть упомянут только один раз в запросе, в новом или старом формате API.

"image": загруженное изображение (используйте формат multipart:часть для указания соответствующей части тела запроса) или публичный URL с изображением (http:, https:).
"roi": интересующая область на изображении. Если данная область не задана, обрабатывается все изображение.
"detector": детектор лиц, который будет применен к изображению (legacy, nnd или prenormalized). Детектор prenormalized принимает нормализованные изображения лиц, при этом стадия обнаружения лица пропускается. Используйте nnd, если вам нужна оценка качества лиц ("quality_estimator": true).
"need_facen": если true, запрос возвращает в ответе вектор признаков.
"need_gender": возвращает пол (старый API).
"need_emotions": возвращает эмоции (старый API).
"need_age": возвращает возраст (старый API).
"need_normalized": возвращает нормализованное изображение лица в формате base64. Нормализованное изображение может быть снова отправлено в findface-extraction-api в режиме детектора prenormalized.
"auto_rotate": если true, автоматически поворачивает исходное изображение в 4-х различных ориентациях и возвращает лица, найденные в каждой из них. Работает, если "detector": "nnd" и "quality_estimator": true.
"attributes": массив строк в формате ["gender", "age", "emotions", "countries47", "beard", "glasses3"], включает распознавание атрибутов лица, переданных в массиве (новый API).

{
    "image": "http://static.findface.pro/sample.jpg",
    "roi": {"left": 0, "right": 1000, "top": 0, "bottom": 1000},
    "detector": "nnd",
    "need_facen": true,
    "need_gender": true,
    "need_emotions": true,
    "need_age": true,
    "need_normalized": true,
    "auto_rotate": true
}

Формат API-ответа 

Типичный ответ компонента findface-extraction-api представляет собой набор ответов на соответствующие запросы, вложенные в основной API-запрос:

{
    "response": [response1, response2, .., responseN]
}

Каждый ответ в наборе содержит следующие данные в формате JSON:

"faces": набор лиц, обнаруженных на предоставленном изображении или в интересующей области изображения.
"error": ошибка обработки запроса (если имела место). Тело ошибки содержит код ошибки, который может быть интерпретирован автоматически ("code") и описание ошибки, удобное для восприятия человеком ("desc").
"facen_model": модель, использованная для извлечения биометрического образца, если "need_facen": true.
"timings": время обработки, если "include_timings": true.

{
    "faces": [face1, face2, .., faceN],
    "error": {
        "code": "IMAGE_DECODING_FAILED",
        "desc": "Failed to decode: reason"
    }
    "facen_model": "elderberry_576",
    "timings": ...

}

Для каждого лица в наборе указываются следующие данные:

"bbox": координаты рамки с лицом.
"detection_score": показатель качества лица или точность обнаружения лица (в зависимости от того, включена ли опция quality_estimator в файле /etc/findface-extraction-api.ini). Прямые изображения лиц анфас считаются наиболее качественными. Для них возвращаются значения вблизи 0, как правило, отрицательные (такие как -0.00067401276, например). Перевернутые лица и лица, повернутые под большими углами, оцениваются отрицательными значениями от -5 и меньше.
"facen": вектор признаков.
"gender": информация о поле (MALE или FEMALE) с указанием точности оценки, если запрашивалась (старый API).
"age": оценка возраста, если запрашивалась (старый API).
"emotions": все доступные эмоции в порядке убывания вероятности, если запрашивались (старый API).
"countries47": вероятные страны происхождения вместе с уверенностью алгоритма в результате, если запрашивались (старый API).
"attributes": пол (male или female), возраст (число лет), эмоции (преобладающая эмоция), вероятные страны происхождения, борода (beard или none), очки (sun, eye, или none), вместе с уверенностью алгоритма в результате, если запрашивались (новый API).
"normalized": нормализованное изображение лица в формате base64, если запрашивалось.
”timings”: время обработки лиц, если запрашивалась.

{
 "bbox": { "left": 1, "right": 2, "top": 3, "bottom": 4},
 "detection_score": 0.99,
 "facen": "...",
 "gender": {
     "gender": "MALE",
     "score": "1.123"
 },
 "age": 23.59,
 "emotions": [
     { "emotion": "neutral", "score": 0.95 },
     { "emotion": "angry", "score": 0.55 },
     ...
 ],
 "normalized": "...",
 "attributes": {
   "age": {
       "attribute": "age",
       "model": "age.v1",
       "result": 25
   },
   "beard": {
       "attribute": "beard",
       "model": "beard.v0",
       "result": [
           { "confidence": 0.015328666, "name": "beard" }
       ]
   },
   "countries47": {
       "attribute": "countries47",
       "model": "countries47.v1",
       "result": [
           { "confidence": 0.90330666, "name": "UKR" },
           { "confidence": 0.013165677, "name": "RUS" },
           { "confidence": 0.009136979, "name": "POL" },
           ...
       ]
   },
   "emotions": {
       "attribute": "emotions",
       "model": "emotions.v1",
       "result": [
           { "confidence": 0.99959123, "name": "neutral" },
           { "confidence": 0.00039093022, "name": "sad" },
           { "confidence": 8.647058e-06, "name": "happy" },
           { "confidence": 7.994732e-06, "name": "surprise" },
           { "confidence": 6.495376e-07, "name": "disgust" },
           { "confidence": 6.063106e-07, "name": "angry" },
           { "confidence": 7.077886e-10, "name": "fear"               }
       ]
   },
   "gender": {
       "attribute": "gender",
       "model": "gender.v2",
       "result": [
           { "confidence": 0.999894, "name": "female" },
           { "confidence": 0.00010597264, "name": "male" }
       ]
   },
   "glasses3": {
       "attribute": "glasses3",
       "model": "glasses3.v0",
       "result": [
           { "confidence": 0.9995815, "name": "none" },
           { "confidence": 0.0003348241, "name": "eye" },
           { "confidence": 8.363914e-05, "name": "sun" }
       ]
   }
 }
 "timings": ...
}

Примеры 

Запрос №1

curl -X POST -F sample=@sample.jpg -F 'request={"requests":[{"image":"multipart:sample","detector":"nnd", "need_gender":true, "need_normalized": true, "need_facen": true}]}' http://127.0.0.1:18666/| jq

Ответ

{
  "responses": [
    {
      "faces": [
        {
          "bbox": {
            "left": 595,
            "top": 127,
            "right": 812,
            "bottom": 344
          },
          "detection_score": -0.0012599,
          "facen": "qErDPTE...vd4oMr0=",
          "gender": {
            "gender": "FEMALE",
            "score": -2.6415858
          },
          "normalized": "iVBORw0KGgoAAAANSUhE...79CIbv"
        }
      ]
    }
  ]
}

Запрос №2

curl -X POST  -F 'request={"requests": [{"need_age": true, "need_gender": true, "detector": "nnd", "roi": {"left": -2975, "top": -635, "right": 4060, "bottom": 1720}, "image": "https://static.findface.pro/sample.jpg", "need_emotions": true}]}' http://127.0.0.1:18666/ |jq

Ответ

{
  "responses": [
    {
      "faces": [
        {
          "bbox": {
            "left": 595,
            "top": 127,
            "right": 812,
            "bottom": 344
          },
          "detection_score": 0.9999999,
          "gender": {
            "gender": "FEMALE",
            "score": -2.6415858
          },
          "age": 26.048346,
          "emotions": [
            {
              "emotion": "neutral",
              "score": 0.90854686
            },
            {
              "emotion": "sad",
              "score": 0.051211596
            },
            {
              "emotion": "happy",
              "score": 0.045291856
            },
            {
              "emotion": "surprise",
              "score": -0.024765536
            },
            {
              "emotion": "fear",
              "score": -0.11788454
            },
            {
              "emotion": "angry",
              "score": -0.1723868
            },
            {
              "emotion": "disgust",
              "score": -0.35445923
            }
          ]
        }
      ]
    }
  ]
}

Запрос №3. Автоповорот

curl -s -F 'sample=@/path/to/your/photo.png' -F 'request={"requests":[{"image":"multipart:sample","detector":"nnd", "auto_rotate": true, "need_normalized": true }]}' http://192.168.113.79:18666/

Ответ

{
 "responses": [
   {
     "faces": [
       {
         "bbox": {
           "left": 96,
           "top": 99,
           "right": 196,
           "bottom": 198
         },
         "detection_score": -0.00019264,
         "normalized": "iVBORw0KGgoAAAANSUhE....quWKAAC"
        },
       {
         "bbox": {
           "left": 205,
           "top": 91,
           "right": 336,
           "bottom": 223
         },
         "detection_score": -0.00041600747,
         "normalized": "iVBORw0KGgoAAAANSUhEUgAA....AByquWKAACAAElEQVR4nKy96XYbybIdnF"
       }
     ]
   }
 ]
}

Запрос №4. Использование нового API (атрибутов: «beard», «emotions», «age», «gender», «glasses3», «face»)

curl -s -F photo=@sample.jpg -Frequest='{"requests": [{"image":"multipart:photo", "detector": "nnd", "attributes": ["beard", "emotions", "age", "gender", "glasses3", "face"]}]}' http://127.0.0.1:18666 | jq

Ответ

{
  "responses": [
    {
      "faces": [
        {
          "bbox": {
            "left": 595,
            "top": 127,
            "right": 812,
            "bottom": 344
          },
          "detection_score": -0.00067401276,
          "rotation_angle": 0,
          "attributes": {
            "age": {
              "attribute": "age",
              "model": "age.v1",
              "result": 25
            },
            "beard": {
              "attribute": "beard",
              "model": "beard.v0",
              "result": [
                {
                  "confidence": 0.015324414,
                  "name": "beard"
                }
              ]
            },
            "emotions": {
              "attribute": "emotions",
              "model": "emotions.v1",
              "result": [
                {
                  "confidence": 0.99958,
                  "name": "neutral"
                },
                {
                  "confidence": 0.0004020365,
                  "name": "sad"
                },
                {
                  "confidence": 8.603454e-06,
                  "name": "happy"
                },
                {
                  "confidence": 8.076766e-06,
                  "name": "surprise"
                },
                {
                  "confidence": 6.6535216e-07,
                  "name": "disgust"
                },
                {
                  "confidence": 6.1434775e-07,
                  "name": "angry"
                },
                {
                  "confidence": 7.3372125e-10,
                  "name": "fear"
                }
              ]
            },
            "face": {
              "attribute": "face",
              "model": "elderberry_576",
              "result": "KjiHu6cWh70ppqa9l"
            },
            "gender": {
              "attribute": "gender",
              "model": "gender.v2",
              "result": [
                {
                  "confidence": 0.9998938,
                  "name": "female"
                },
                {
                  "confidence": 0.000106243206,
                  "name": "male"
                }
              ]
            },
            "glasses3": {
              "attribute": "glasses3",
              "model": "glasses3.v0",
              "result": [
                {
                  "confidence": 0.99958307,
                  "name": "none"
                },
                {
                  "confidence": 0.00033243417,
                  "name": "eye"
                },
                {
                  "confidence": 8.4465064e-05,
                  "name": "sun"
                }
              ]
            }
          }
        }
      ],
      "orientation": 1
    }
  ]
}

Прямые API-запросы к findface-extraction-api

API-запросы

Формат API-ответа

Примеры

Прямые API-запросы к `findface-extraction-api`

API-запросы 

Формат API-ответа 

Примеры 