How to Use Biometric API

In this section:


Biometric API requests are to be sent to http://<findface-sf-api IP address>:18411/. API requests are executed by the findface-sf-api component.

API Version

The API version is increased every time a major change is made and allows us to avoid breaking backwards compatibility. The API version is to be specified in the request path (for example, v2 in /v2/detect/).

The most recent version is v2.


When starting a new project, always use the latest stable API version.

Face as API Object

Biometric API operates with a face object which represents a human face.


There can be several faces in a photo and thus several face objects associated with it.


Different images of the same person are considered to be different face objects.

Each face object has the following attributes:

  • "id" (uint64): (only if the face has been added to the biometric database) face identifier (uint64) to be specified by a user in an API request when adding a face from memcached to the database. The identifier is passed as <id> in the /galleries/<gallery>/faces/<id> POST method.
  • "facen" (bytes): the face feature vector.
  • "meta" (string): set of metadata strings that you can use to store any information associated with the face, for example, the name of a person, the camera id, the detection date and time, etc.
  • "features" (dictionary): a dictionary {key (string):value (any datatype)}. Used to store face biometric parameters such as gender, age, emotions.

Parameters Format

There are two ways to pass a photo image to the system:

  • as a publicly accessible URL,
  • as a file.

There are three ways to pass parameters to the biometric API:

  • image/jpeg, image/png, image/webp, image/bmp: to pass a photo image as a file,
  • text/x-url: to pass a photo image as an URL,
  • query string: parameters appended to a URI request.

All responses are in JSON format and UTF-8 encoding.

How to Use Examples

Examples in methods descriptions illustrate possible method requests and responses. To check the examples without writing code, use the embedded API framework. To access the framework, enter in the address bar of your browser: http://<findface-sf-api_ip>:18411/v2/docs/v2/overview.html for the API version /v2.


FindFace Enterprise Server imposes the following limits.

Limit Value
Image formats JPG, PNG, WEBP, BMP
Maximum photo file size To be configured via the findface-sf-api configuration file.
Minimal size of a face 50x50 pixels
Maximum number of detected faces per photo Unlimited


Additionally, the URL provided to the API to fetch an image must be public (without authentication) and direct (without any redirects).

Error Reporting

If a method fails, it always returns a response with a HTTP code other than 200, and a JSON body containing the error description. The error body always includes at least two fields: code and desc.

  • code is a short string in CAPS_AND_UNDERSCORES, usable for automatic decoding.
  • desc is a human-readable description of the error and should not be interpreted automatically.

Common Error Codes

Error code Description HTTP code
UNKNOWN_ERROR Error with unknown origin. 500
BAD_PARAM The request can be read, however, some method parameters are invalid. This response type contains additional attributes param and``value`` to indicate which parameters are invalid. 400
CONFLICT Conflict. 409
EXTRACTION_ERROR Error upon a face feature vector extraction. 503
LICENSE_ERROR The system configuration does not match license. 503
MALFORMED_REQUEST The request is malformed and cannot be read. 400
OVER_CAPACITY The findface-extraction-api queue length has been exceeded. 429
SOURCE_NOT_FOUND The face in the from parameter does not exist. 400
SOURCE_GALLERY_NOT_FOUND The gallery in the from parameter does not exist. 400
STORAGE_ERROR The biometric database not available. 503
CACHE_ERROR Memcached not available. 503
NOT_FOUND Matching faces not found. 404
NOT_IMPLEMENTED This functionality not implemented. 501
GALLERY_NOT_FOUND Matching galleries not found. 404