Skip to content

Face Identification Module (1:N)

This module lets you match a face from an image against a database of faces. You can create and manage such a database with identities, upload photos and associate them with names. So, when you show the system a photo, it can search for a match in the database.

Module entities

Person

Person is an identity that contains the following components:

  • Name
  • Set of images
  • Metadata
  • Groups

metadata is a regular json object specified by the end app. To retrieve a list of persons, you can fetch it from the group endpoint using the following URL format:

/api/groups/{groupId}/persons

When searching for a Person by an Image, the system calculates a descriptor to match against the existing entries. If a match is not found, a new person entry is created. This means that you can reuse the descriptor calculated during the search process when creating a new person entry.

For creating Persons, the image can be passed as a file using the content field, or as a link using the imageUrl field. Make sure to use a photo with only one face in it. If you use an image with multiple faces, the system will automatically select the central face for the created person.

The web service accepts the following types of links:

Note that if you use both content (base64 string of the image) and imageUrl, content takes priority.

The service should be configured with the necessary access and permissions to access the specified files or URLs.

Image

A photo of Person. You can add any number of Images to a Person and remove them at any time. The original image can be compressed by using the resizeOptions field and specifying parameters such as width, height, and quality. Note that in this case the descriptor will be computed based on the compressed image.

Group

A set of Persons. You can create any number of Groups, add or remove Persons from them at any time. Each Person can be a member of many Groups. When creating a new person, you can specify the groups they should belong to using the groups field. If no groups are specified, the person will be added to the default group. See API docs.

You can Group photos in the database and then search by the Group you need, for example, create a Fraudsters group and look for scammers in it.

Identifying All Faces in Image

To search for all faces in an image and match them against a database, set the detectAll property to true. Use outputImageParams to define image settings, such as image size and aspect ratio, for the face images that will be returned in the identification response, the detection field. Find more information in the OpenAPI specification.

Similarity Threshold

While searching, you can use the similarity threshold: The more a person in a database photo looks similar to the person who is being looked for, the lower the similarity distance will be. See the threshold parameter.

In the search result, the distance similarity score is used for ranking: the lower the returned distance value, the more the face on the corresponding photo is similar to the one submitted for the search. So, if you set the maximum value of threshold in the request, even the dissimilar results will be returned with estimated similarity distance for each one.

Search Time and Database Size

The horizontal scaling is supported, so the search time is guaranteed regardless of the size of the database and the flow of incoming requests. Just make sure to provide the computing power.

Time to Live

The ttl (Time-To-Live) parameter sets the lifespan of the Person's records in seconds. In the example below, the Person will automatically be removed after 120 seconds:

{
    "name": "test_person 1",
    "metadata": {},
    "ttl": 120
}

See more details in the Cleaning Up Data article.