Test Requests

Before you can proceed with development to implement the face recognition services to your system, make sure that the FindFace Server components are working. To do so, run the test requests below, minding the sequence. To pretty-print responses, we recommend you to use jq.

In this section:

How to Pretty-Print Responses

Use jq to parse JSON data in responses. The jq tool is automatically installed from the console installer.

Tip

If it is not so, install jq as such:

sudo apt install jq

Note

Since jq approximates integers larger than 2^53 (e.g., for "id":12107867323949968228, the output is "id": 12107867323949967000, etc.), you may want to use json_pp instead.

List Galleries

The following request returns the names of existing galleries (galleryname). Relevant HTTP API method: /galleries GET.

Request

curl -s http://localhost:18411/v2/galleries | jq

Response

{
  "galleries": [
    {
      "name": "galleryname",
      "faces": 0
    }
  ]
}

Detect Face in Image

The 1st request detects a face in a sample Internet image and returns coordinates of the rectangle around the face (a.k.a. bbox) and the face orientation. Relevant HTTP API method: /detect POST.

Request #1

curl -s -H 'Content-Type: text/x-url' -d https://static.findface.pro/sample.jpg -X POST http://localhost:18411/v2/detect | jq

Response

{
  "faces": [
    {
      "bbox": {
        "left": 595,
        "top": 127,
        "right": 812,
        "bottom": 344
      },
      "features": {
        "score": 0.9999999
      }
    }
  ],
  "orientation": 1
}

If facen=on, the detection result is saved in memcached. In the 2nd request, the image is the same but this time facen=on, along with enabled gender, age and emotions recognition.

Tip

To retrieve the detection result from memcached, use the /detect GET method.

Request #2

curl -s -H 'Content-Type: text/x-url' -d https://static.findface.pro/sample.jpg -X POST 'http://localhost:18411/v2/detect?facen=on&gender=on&age=on&emotions=on' | jq

Response

{
  "faces": [
    {
      "id": "bhse5elubdg0ajgm2nkg",
      "bbox": {
        "left": 595,
        "top": 127,
        "right": 812,
        "bottom": 344
      },
       "features": {
        "gender": {
          "gender": "FEMALE",
          "score": -2.6415923
        },
        "age": 26.04833,
        "score": 0.9999999,
        "emotions": [
          {
            "emotion": "neutral",
            "score": 0.99958
          },
          {
            "emotion": "sad",
            "score": 0.0004020398
          },
          {
            "emotion": "happy",
            "score": 8.603504e-06
          },
          {
            "emotion": "surprise",
            "score": 8.076798e-06
          },
          {
            "emotion": "disgust",
            "score": 6.653509e-07
          },
          {
            "emotion": "angry",
            "score": 6.14346e-07
          },
          {
            "emotion": "fear",
            "score": 7.33713e-10
          }
        ]
      }
    }
  ],
  "orientation": 1
}

The 3rd request detects a face in another image and is used merely for the purpose of database population. The detection result is saved in memcached (facen=on).

Request #3

curl -s -H 'Content-Type: text/x-url' -d https://static.findface.pro/sample2.jpg -X POST 'http://localhost:18411/v2/detect?facen=on

{
  "faces": [
    {
      "id": "bhse45dubdg0ajgm2nk0",
      "bbox": {
        "left": 515,
        "top": 121,
        "right": 821,
        "bottom": 427
      },
      "features": {
        "score": 0.9999982
      }
    }
  ],
  "orientation": 1
}

Retrieve Detection Result from memcached

The following request retrieves the detection result from memcached by id. Related HTTP API method: /detect GET.

Note

bhse5elubdg0ajgm2nkg is the id of the detection results in memcached. This id is provided only for reference. To create valid requests out of the example, replace the identifier with those actually received in the previous responses.

Important

Before you proceed, open the findface-sf-api configuration file and make sure that the allow-return-facen parameter is on.

sudo vi /etc/findface-sf-api.ini

allow-return-facen: on

Request #1

curl -s 'http://localhost:18411/v2/detect/bhse5elubdg0ajgm2nkg'

Response

{
  "id": "bhse5elubdg0ajgm2nkg",
  "bbox": {
    "left": 595,
    "top": 127,
    "right": 812,
    "bottom": 344
  },
  "features": {
    "score": 0.9999999
  }
}

To retrieve a face feature vector (facen) in a detection result, open the /etc/findface-sf-api.ini configuration file and set allow-return-facen: true. Restart findface-sf-api and append the return_facen=on query string parameter to the previous command:

Request #2

curl -s 'http://localhost:18411/v2/detect/bhse5elubdg0ajgm2nkg?return_facen=on' | jq

Response

{
  "id": "bhse5elubdg0ajgm2nkg",
  "bbox": {
    "left": 595,
    "top": 127,
    "right": 812,
    "bottom": 344
  },
  "features": {
    "score": 0.9999999
  },
  "facen": "1ji...Vr3TEQg8"
}

Compare Faces

The following requests compare a pair of faces and return a probability of their belonging to the same person. Relevant HTTP API method: /verify POST.

The first request compares 2 results of the /detect POST method, stored in memcached.

Request #1

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

Response

{
  "confidence": 0.92764723
}

The 2nd request compares a result of the /detect POST method and a face in a gallery.

Request

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

Response

{
  "confidence": 0.999996
}