Face Recognition and Document Reconciliation
Handl provides 3 methods for face detection:
The
/face/detectmethod 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/distancemethod 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/selfiemethod 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 thesame_faceparameter, 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
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
image
string
File in which you want to find people's faces
{
{ "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
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
image1
string
1st file, in which you need to find a face
image2
string
2nd file, in which you need to find a face
{
{ "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
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
image
string
file in which you want to compare faces
{
{ "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
}Last updated
Was this helpful?