Face Recognition and Document Reconciliation

Handl provides 3 methods for face detection:

• The /face/detect method takes 1 image as input, searches for people's faces, and returns their coordinates in the response. The faces of people in the input image can be represented on documents, such as a passport photo.

• The /face/distance method accepts two images, each of which finds a person's face, then compares them and returns the probability of a face mismatch in the response.

• The /face/selfie method takes as input 1 image, a "selfie" of a person holding the document that also contains an image of their face. It searches the image for the person's face and their photo in the document, and then compares the two found faces. The answer is the same_face parameter, which returns the value true if the photo and the document contain the face of the same person, and false otherwise.

Probability of matching faces "distance"

The parameter distance in the response shows the probability of a mismatch of two detected faces in the input data:

• 0.50-1.00 - faces do not match, they are different people (same_face="false")

• 0.00-0.49 - faces match, it is the same person (same_face="true")

API specification

Below is the API specification for the 3 face recognition methods. For more details on how to compile the query, see Connecting and testing.

detect

POST https://latest.handl.ai/face/detect

Query Parameters

Name	Type	Description
return_crops	boolean	true (default) - the answer will return the areas with faces clipped from the image in base64 format. false - disables the return of areas with faces.
async	boolean	true - request in asynchronous mode, see. "Asynchronous mode" in the "Connecting" section. false - request in the synchronous mode.
priority	integer	Task priority, by default it takes the value "1"

Request Body

Name	Type	Description
image	string	File in which you want to find people's faces

200 Request is successful

{
  { "detail": [], // technical information
  { "items": [
    {
      "reason": null, // explanations in case of an error are displayed here
      { "faces": [
        {
          "confidence": 0.699973, // level of confidence that the cutout is really a face
          "description": "face", // description of the found area, in the detect method it is always "face"
          "type": "face", // type of detected area, always "face" in the method detect
          "page": 1, // number of the page, where the face was found
          "rotation": 0, // horizontal and vertical orientation of the face
          "coords": [ // coordinates of the rectangle circumscribed around the found face in the image
            [
              176,
              1385
            ],
            [
              427,
              1385
            ],
            [
              427,
              1696
            ],
            [
              176,
              1696
            ]
          ],
          "coords_relative": [ // relative coordinates of the rectangle circumscribed around the found face in the image
            [
              0.11278792692613185,
              0.6767922235722964
            ],
            [
              0.2732327243844321,
              0.6767922235722964
            ],
            [
              0.2732327243844321,
              0.8286755771567436
            ],
            [
              0.11278792692613185,
              0.8286755771567436
            ]
          ],
          "crop": "data:image/jpeg;base64,<...>" // cut rectangle from image in binary format
        }
      ]
    }
  ],
  "task_id": null, //task's internal id
  "code": null, // error code
  "message": null, // error message within the object
  "errno": null, // error number
  "traceback": null, // error message within the limits of object
  "fake": null, // not used in this method
  "pages_count": null, // not used in this method
  "docs_count": null // not used in this method
}

distance

POST https://latest.handl.ai/face/distance

Query Parameters

Name	Type	Description
return_crops	string	true (default) - the answer will return the areas cut out of the image in base64 format. false - disables the return of cut out areas with faces.
async	boolean	true - request in asynchronous mode, see. "Asynchronous mode" in the "Connection" section. false - request in the synchronous mode.
priority	integer	Task priority, assumes the value of “1” by default.

Request Body

Name	Type	Description
image1	string	1st file, in which you need to find a face
image2	string	2nd file, in which you need to find a face

200 The request is successful

{
  { "detail": [], // technical information
  { "items": [
    {
      "distance": 0.9033318, // probability of mismatch of two detected faces in the input data
      "reason": null, // explanations in case of mistake are displayed here
      "same_face": false, // Dbrain's verdict on whether the faces are the same
      "faces1": [
        {
          "confidence": 0.7, // level of confidence that the cutout is really a face
          "description": "face", // description of the found area, in the distance method it is always "face"
          "type": "face", // type of the found area, always "face" in the distance method
          "page": 1, // number of the page, where the face was found
          "rotation": 0, // horizontal and vertical orientation of the face
          "coords": [ // coordinates of the rectangle circumscribed around the found face in the image
            [
              420,
              273
            ],
            [
              1236,
              273
            ],
            [
              1236,
              1434
            ],
            [
              420,
              1434
            ]
          ],
          "coords_relative": [ // relative coordinates of the rectangle circumscribed around the found face in the image
            [
              0.18108974358974358,
              0.0885009030704395
            ],
            [
              0.5328525641025641,
              0.0885009030704395
            ],
            [
              0.5328525641025641,
              0.4647802528597231
            ],
            [
              0.18108974358974358,
              0.4647802528597231
            ]
          ],
          "crop": "data:image/jpeg;base64,<...>" // the rectangle cut out of the image in binary format
        }
      ],
      }, "faces2": [
        {
          { "confidence": 0.7,
          { "description": { "face",
          { "type": "face",
          { "page": 1,
          "rotation": 0,
          { "coords": [
            [
              211,
              35
            ],
            [
              576,
              35
            ],
            [
              576,
              523
            ],
            [
              211,
              523
            ]
          ],
          { "coords_relative": [
            [
              0.2813333333333333,
              0.035
            ],
            [
              0.768,
              0.035
            ],
            [
              0.768,
              0.523
            ],
            [
              0.2813333333333333,
              0.523
            ]
          ],
          "crop": "data:image/jpeg;base64,<...>"
        }
      ]
    }
  ],
  "task_id": null, //task's internal id
  "code": null, // error code
  "message": null, // error message within the object
  "errno": null, // error number
  "traceback": null, // error message within the limits of object
  "fake": null, // not used in this method
  "pages_count": null, // not used in this method
  "docs_count": null // not used in this method
}

selfie

POST https://latest.handl.ai/face/selfie

Query Parameters

Name	Type	Description
return_crops	boolean	true (default) - the answer will return the areas with faces cut out from the image in base64 format. false - disables the return of cut out areas with faces
simple	string	default (the default option) - the algorithm compares the face in the given image with the face in the target document type. simple - the algorithm compares two faces in the image, without checking the document and its type
doc_type	string	The name of the document type on the selfie image. For example, if the target document for comparison with the selfie is a passport, then you must specify the value passtront_main. Any other target document is specified according to the type names in the specification.
simple_cropper	boolean	false (default) - the simplified algorithm of cutting documents from images is not used true - the simplified algorithm of cutting documents from images is used: it works faster but gives less exact results. On images with a complex background documents may be cut out less accurately.
async	boolean	true - Query in asynchronous mode, see "Asynchronous Mode". "Asynchronous mode" in the "Connection" section. false - request in the synchronous mode
priority	integer	Task priority, assumes the value of “1” by default.

Request Body

Name	Type	Description
image	string	file in which you want to compare faces

200

{
  { "detail": [], // technical information
  { "items": [
    {
      "distance": 0.35919100000000004, // probability of mismatch of two detected faces in the input data 
      "reason": null, // reason why the face image was not detected
      "same_face": true, // = "true" if the faces match; = "false" otherwise
      "faces": [
        {
          "confidence": 0.697779, // level of confidence that the cutout is really a face
          "description": "face", // description of the found area
          "type": "face", // type of area found
          "page": 1, // number of the page, on which the face was found
          "rotation": 0, // horizontal and vertical orientation of the face
          "coords": [ // coordinates of the rectangle circumscribed around the found face in the image
            [
              1381,
              357
            ],
            [
              2104,
              357
            ],
            [
              2104,
              1243
            ],
            [
              1381,
              1243
            ]
          ],
          "coords_relative": [ // relative coordinates of the rectangle circumscribed around the found face in the image
            [
              0.5397111913357401,
              0.18604651162790697
            ],
            [
              0.822503008423586,
              0.18604651162790697
            ],
            [
              0.822503008423586,
              0.6479550922213312
            ],
            [
              0.5397111913357401,
              0.6479550922213312
            ]
          ],
          "crop": "data:image/jpeg;base64,<...>"
        }
      ],
      }, "faces_on_document": [
        {
          { "confidence": 0.69999,
          { "description": { "face_on_doc",
          { "type": "face_on_doc",
          { "page": 1,
          "rotation": 0,
          { "coords": [
            [
              309,
              1206
            ],
            [
              525,
              1212
            ],
            [
              520,
              1462
            ],
            [
              304,
              1456
            ]
          ],
          { "coords_relative": [
            [
              0.1208105501457182,
              0.6282101141561518
            ],
            [
              0.20510919790904614,
              0.6315200298424686
            ],
            [
              0.20321649818970494,
              0.7618871788939843
            ],
            [
              0.11892901155920069,
              0.7586366781394492
            ]
          ],
          "crop": "data:image/jpeg;base64,<...>"
        }
      ],
      { "document": {
        { "confidence": 1,
        { "description": { "document",
        { "type": "passport_main",
        { "page": 1,
        "rotation": 0,
        { "coords": [
          [
            176,
            176
          ],
          [
            1347,
            213
          ],
          [
            1315,
            1828
          ],
          [
            145,
            1795
          ]
        ],
        { "coords_relative": [
          [
            0.06875,
            0.09166666666666666
          ],
          [
            0.5261718750000001,
            0.1109375
          ],
          [
            0.513671875,
            0.9520833333333333
          ],
          [
            0.056640625,
            0.9348958333333334
          ]
        ],
        "crop": "data:image/jpeg;base64,<...>"
      }
    }
  ],
  "task_id": null, //task's internal id
  "code": null, // error code
  "message": null, // error message within the object
  "errno": null, // error number
  "traceback": null, // error message within the limits of object
  "fake": null, // not used in this method
  "pages_count": null, // not used in this method
  "docs_count": null // not used in this method
}