Object API Methods v2

In this section:

Detect Methods

Detect Face on the Photo

POST /v2/detect

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 extraction-api component, so the sf-api component formats your initial request and forwards it to extraction-api.

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 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 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 sf-api configuration file.

  • "attribute": array of strings in the format ["gender", "age", "emotions", "countries47", "beard", "glasses3"], enables recognition of the face features passed in the array (new API).

  • roi: string, a region of interest in the image, takes an array of integers in the format roi=top,left,right,bottom, (e.g. {“left”: 0, “right”: 1000, “top”: 0, “bottom”: 1000}).

Tip

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

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 you form a request, 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. Old and new API simultaneous usage

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

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
}

Get Detection Result from the Cache by ID

GET /v2/detect/:id

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

Parameters in path segments:

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

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 extraction-api Response

POST /v2/detect/:id

This method creates a detection result out of a 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

{}

Get Normalized Detect by ID

GET /v2/detect/:id/normalized

This method retrieves normalized detect by ID.

Parameters in path segments:

  • :id: ID.

Returns:

Normalized object images on success.

Example

Request

curl -i http://127.0.0.1:18411/v2/detect/bg2gu31jisghl6pee09g/normalized

Response:

HTTP/1.1 200 OK
Content-Type: image/png
X-Request-Id: SF:mjv3Lyvf
Date: Thu, 09 Apr 2020 15:59:48 GMT
Transfer-Encoding: chunked

Warning: Binary output can mess up your terminal. Use "--output -" to tell
Warning: curl to output it to your terminal anyway, or consider "--output
Warning: <FILE>" to save to a file.

Compare Faces

GET /v2/verify

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 (in the format detection:<id>), or one from the biometric database (in the format face:<gallery>/<id> or facen:[model:]<base64 facen> if allow-return-facen:true ).

  • "face2": the second face, from the same possible sources as the first object.

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
}