Biometric API Methods

In this section:

Detect Face in Image

/detect POST

This method detects a face in a provided image and returns coordinates of the rectangle around the face (a.k.a. bbox) and the face orientation.

Note

Face detection is done by the findface-extraction-api component, so the findface-sf-api component formats your initial request and forwards it to findface-extraction-api.

Important

Be sure to pass the enabled facen parameter in the /detect POST query string in order to save the returned result in memcached. To retrieve the returned result from memcached, use the /detect GET method.

Tip

To enable a boolean parameter (gender, age, etc.), use any of the following strings: 1, yes, true, or on, in any letter case.

Important

To enable recognition of face features, you can use either the new (preferred) or old API parameters (see the query string parameters for details). The old API allows you to recognize gender, age, emotions, and country, while the new API provides recognition of gender, age, emotions, country, beard, and glasses. Each face feature (gender, age, emotions, country, beard, or glasses) must be mentioned only once in a request, either in the new or old API format.

Query string parameters:

  • "detector": string, face detector to be applied to the image: nnd (regular detector) or normalized (accepts a normalized face image, skipping the face detection stage).
  • "gender": Boolean, enables gender recognition (old API).
  • "age": Boolean, enables age recognition (old API).
  • "emotions": Boolean, enables emotions recognition (old API).
  • "facen": Boolean, the formatted request to findface-extraction-api will include such parameters as need_facen (extract a face feature vector) and need_normalized (obtain a normalized face image), while the full findface-extraction-api response will be saved in memcached under a temporary UUID. You can find this UUID in the id field of the response.
  • "countries47:: Boolean, enables country recognition (old API).
  • "autorotate": Boolean, auto-rotates an original image to 4 different orientations and returns faces detected in each orientation.
  • "return_facen": Boolean, returns a face feature vector in the response. Requires the enabled allow-return-facen flag in the findface-sf-api configuration file.
  • "attributes": Array of strings in the format ["gender", "age", "emotions", "countries47", "beard", "glasses3"], enables recognition of the face features passed in the array (new API).

Parameters in request body:

Image as a file of the image/jpeg, image/png, or image/webp MIME-type, or as a text/x-url link to a relevant public URL.

Returns:

  • list of coordinates of the rectangles around the detected faces;

  • temporary UUID of the detection result (id, if facen enabled);

    Important

    When writing code, be sure to check the relevance of the temporary UUID before you refer to it as it tends to become irrelevant with time. If so, re-detect the face.

  • feature vector (if return_facen enabled);

  • gender (if gender enabled): male or female, with algorithm confidence in the result ("score");

  • age (if age enabled): number of years;

  • emotions (if emotions enabled): 6 basic emotions + neutral (angry, disgust, fear, happy, sad, surprise, neutral) with algorithm confidence in each emotion expression;

  • countries (if countries47 enabled): probable countries of origin with algorithm confidence in the result;

  • attributes (if passed): gender (male or female), age (number of years), emotions (predominant emotion), probable countries of origin, beard (beard or none), glasses (sun, eye, or none), along with algorithm confidence in the result;

  • orientation.

Example

Request

curl -i -X POST 'http://127.0.0.1:18411/v2/detect?facen=on&gender=on&age=on&emotions=on&attribute=glasses3' -H 'Content-Type: image/jpeg' --data-binary @sample.jpg
HTTP/1.1 100 Continue

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: SF:BpLnfgDs
Date: Thu, 23 May 2019 12:00:22 GMT
Content-Length: 713

{
    "faces": [
        {
            "id": "bjj8mlhjisgjrk6hj1v0",
            "bbox": { "left": 595, "top": 127, "right": 812, "bottom": 344 },
            "features": {
                "gender": { "gender": "FEMALE", "score": 0.9998938 },
                "age": 25,
                "score": -0.000696103,
                "emotions": [
                    { "emotion": "neutral", "score": 0.99958 },
                    { "emotion": "sad", "score": 0.0004020365 },
                    { "emotion": "happy", "score": 8.603454e-06 },
                    { "emotion": "surprise", "score": 8.076766e-06 },
                    { "emotion": "disgust", "score": 6.6535216e-07 },
                    { "emotion": "angry", "score": 6.1434775e-07 },
                    { "emotion": "fear", "score": 7.3372125e-10 }
                ],
                "attributes": {
                    "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
}

Retrieve Detection Result from memcached

/detect/:id GET

This method retrieves the detection results from memcached by their temporary UUID’s (including feature vectors of the detected faces).

Parameters in path segments:

  • :id: the detection result temporary UUID in memcached.

Returns:

JSON representation of the detection result.

Example

Request

curl -i -X GET 'http://127.0.0.1:18411/v2/detect/bg2gu31jisghl6pee09g'

Response:

{
    "bbox": { "bottom": 343, "left": 593, "right": 824, "top": 112 },
    "features": {
        "age": 26.096783,
        "emotions": [
            { "emotion": "neutral", "score": 0.9094986 },
            { "emotion": "happy", "score": 0.11464329 },
            { "emotion": "sad", "score": 0.005675929 },
            { "emotion": "surprise", "score": -0.02556022 },
            { "emotion": "fear", "score": -0.14499822 },
            { "emotion": "angry", "score": -0.19491306 },
            { "emotion": "disgust", "score": -0.31617728 }
        ],
        "gender": { "gender": "FEMALE", "score": -2.7309942 },
        "score": -0.000696103
    },
    "id": "bg2gu31jisghl6pee09g"
}

Create Detection Result out of findface-extraction-api Response

/detect/:id POST

This method creates a detection result out of a findface-extraction-api response.

Parameters in path segments:

  • :id: specify UUID under which the newly created detection result will be stored in cache.

Returns:

Empty JSON on success.

Example

Request

$ curl -i -X POST 'http://127.0.0.1:18411/v2/detect/bg2gu31jisghl6peea9g' -H 'Content-Type: application/json' --data-binary '@extapi-face.json'

Response:

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: jFSBuSPm
Date: Wed, 05 Dec 2018 08:08:56 GMT
Content-Length: 2

{}

List Database Galleries

/galleries GET

This method returns the list of all galleries in the biometric database.

Parameters:

The method doesn’t accept any parameters.

Returns:

JSON dictionary with the list of gallery names.

Example

Request

GET /v2/galleries HTTP/1.1
Host: 172.17.47.19:18411

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Fri, 02 Feb 2018 10:11:43 GMT
Content-Length: 35

{"galleries":[{"name":"sandbox"}]}

Add Face from memcached to Database

/galleries/:gallery/faces/:id POST

This method not only retrieves a detected face (a result of the /detect POST method) from memcached by its temporary UUID but also adds the face along with its feature vector to a database gallery under a custom id. The custom id and database gallery are to be specified in the path segments. Along with the face, you can also add metadata which describe the person in a unique way, for example, the person’s name.

Parameters in path segments:

  • :gallery: the name of the gallery to add the face in.
  • :id: permanent face id in the gallery, uint64.

Parameters in request body:

  • "from": temporary UUID of the detected face in memcached,
  • "meta" [optional]: the person’s metadata such as the person’s name, original image details, detection date and time, etc., dictionary.

Returns:

  • JSON representation of the added face on success.
  • Error on failure.

Example

Request

curl -i -X POST http://127.0.0.1:18411/v2/galleries/hello/faces/123/ -H 'Content-Type: application/json' --data-binary '@-' <<EOF
{
    "from": "detection:bg2gu31jisghl6pee09g",
    "meta": {
        "camera": "openspace",
        "labels": ["foo", "bar"],
        "timestamp": "1543837276"
    }
}
EOF

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: SF:OSSKbJg3
Date: Wed, 05 Dec 2018 08:27:59 GMT
Content-Length: 555

{
    "features": {
        "age": 26.096783,
        "emotions": [
            { "emotion": "neutral", "score": 0.9094986 },
            { "emotion": "happy", "score": 0.11464329 },
            { "emotion": "sad", "score": 0.005675929 },
            { "emotion": "surprise", "score": -0.02556022 },
            { "emotion": "fear", "score": -0.14499822 },
            { "emotion": "angry", "score": -0.19491306 },
            { "emotion": "disgust", "score": -0.31617728 }
        ],
        "gender": { "gender": "FEMALE", "score": -2.7309942 },
        "score": -0.000696103
    },
    "id": { "face": 123, "gallery": "hello" },
    "meta": {
        "camera": "openspace",
        "labels": ["foo", "bar"],
        "timestamp": "1543837276"
    },
    "normalized_id": "123_bg2hcupjisghl6pee0ag.png"
}

Compare Faces

/verify POST

This method compares a pair of faces and returns a probability of their belonging to the same person (a.k.a. similarity, or confidence).

Query string parameters:

  • "face1": the first face, either a detection result (a result of the /detect POST method being stored in memcached), or one from the biometric database.
  • "face2": the second face, from the same possible sources as the first face.

Returns:

Algorithm confidence that the faces match.

Example

Request #1. Compare 2 detection results

curl -s 'http://172.17.47.19:18411/v2/verify?face1=detection:bd3hv4tt8f66ph0eag1g&face2=detection:bd3hv8dt8f66ph0eag2g' | jq

Response

{
  "confidence": 0.92764723
}

Request #2. Compare a detection result and a face from a gallery

curl -s 'http://172.17.47.19:18411/v2/verify?face1=detection:bd3hv4tt8f66ph0eag1g&face2=face:galleryname/2' | jq

Response

{
  "confidence": 0.999996
}