Skip to content

Face Comparison

On this page, find detailed information about faces comparison in Face SDK Web API.


To perform a comparison of faces in the same image or in two different images, use POST /api/match.


The SDK can compare faces in the same image or in two different images. This is defined by the type parameter.

The request contains the following parameters:

└── images
|   └── data
|   └── index
|   └── detectAll
|   └── type
└── thumbnails
Parameter Description
images The array of all images included in the comparison: data, index, detectAll, type for each image.
data Base64 image
index The image index number.

Whether to detect all faces in the image. If set to false, only one face is detected: the most central one.


The type of the image, defines the way the comparison is performed. Should be set by a user.

See the list of image types


Whether to return thumbnail: Base64 cropped image that contain vertically aligned faces.

Default: false.


Before comparing faces, the Face SDK detects them. The detection result is displayed in the detections field.

Each face is identified by two parameters: faceIndex (the index number of the face) and imageIndex (the index number of the image on which the face is detected).

So, if there are two images each of which has two faces on them and all index numbers start from 0, the parameters will be the following:

First face in the first image:"faceIndex": 0, "imageIndex": 0

Second face in the first image: "faceIndex": 1, "imageIndex": 0

First face of the second image: "faceIndex": 0, "imageIndex": 1

Second face in the second image: "faceIndex": 1, "imageIndex": 1

The response contains the following parameters:

└── ErrorCode
└── code
└── detections
|   └── faces
|   |   └── faceIndex
|   |   └── landmarks
|   |   └── roi
|   |   └── rotationAngle
|   |   └── thumbnail
|   └── imageIndex
|   └── status
└── results
|   └── first
|   └── firstFaceIndex
|   └── firstIndex
|   └── score
|   └── second
|   └── secondFaceIndex
|   └── secondIndex
|   └── similarity
Parameter Description
ErrorCode Legacy parameter.

The result code the SDK returns.

If everything is OK, the result looks as follows:

"ErrorCode": 0,

"code": 0

See the list of error codes

detections The array of detected faces. Includes faces, imageIndex, status.
faces The array of detected faces. Includes faceIndex, landmarks, roi, rotationAngle, thumbnail for each of the detected faces.
faceIndex The detected face index number.
landmarks Returns absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips.
roi The rectangular area of a detected face that is represented by a set of four elements: the X and Y coordinates of the top-left point, and the width and height dimensions of the rectangle.
rotationAngle Angle of rotation of the face from the vertical axis, degrees.
thumbnail Base64 cropped image that contains the vertically aligned face.
imageIndex The image index number. Can be given; if not given, the index numbers are set automatically starting from 0. All index numbers must be whole and unique—not repeated.

Returns the same value as code. If "code": 0 everything is OK. First status is detected, and if something is wrong, it is returned in code as well.

Possible errors:

"status": 1—image is empty, try again with another image

"status": 2—face is not detected

"status": 6—data can not be decoded as image

results The comparison results include first, firstFaceIndex, firstIndex, score, second, secondFaceIndex, secondIndex, similarity for each comparison of two faces.
first type (see the Request parameters) of the first compared face.
firstFaceIndex faceIndex of the first compared face.
firstIndex imageIndex of the image on which the first compared face is detected.
score A dimensionless number that shows how similar the compared faces are. 0—absolutely identical faces.
second type (see the Request parameters) of the second compared face.
secondFaceIndex faceIndex of the second compared face.
secondIndex imageIndex of the image on which the second compared face is detected.

The detected faces similarity, %.

100%—absolutely identical faces, 0%—absolutely not identical.

To compare several images from a document and look up a person in the database in one request, use POST /api/match_and_search. In this case, the calculation of the discriptor will be performed only once, as opposed to using two requests for the same operation.

Find comprehensive information in OpenAPI documentation.