How to Use Biometric API
In this section:
Endpoint
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.
Tip
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.
Note
There can be several faces in a photo and thus several face objects associated with it.
Note
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 frommemcachedto the database. The identifier is passed as <id> in the/galleries/<gallery>/faces/<id> POSTmethod."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.
Limits
FindFace Enterprise Server imposes the following limits.
Limit |
Value |
|---|---|
Image formats |
JPG, PNG, WEBP, BMP |
Maximum photo file size |
To be configured via the |
Minimal size of a face |
50x50 pixels |
Maximum number of detected faces per photo |
Unlimited |
Important
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.
codeis a short string inCAPS_AND_UNDERSCORES, usable for automatic decoding.descis a human-readable description of the error and should not be interpreted automatically.
Common Error Codes
Error code |
Description |
HTTP code |
|---|---|---|
|
Error with unknown origin. |
500 |
|
The request can be read, however, some method parameters are invalid. This response type
contains additional attributes |
400 |
|
Conflict. |
409 |
|
Error upon a face feature vector extraction. |
503 |
|
The system configuration does not match license. |
503 |
|
The request is malformed and cannot be read. |
400 |
|
The |
429 |
|
The face in the |
400 |
|
The gallery in the |
400 |
|
The biometric database not available. |
503 |
|
Memcached not available. |
503 |
|
Matching faces not found. |
404 |
|
This functionality not implemented. |
501 |
|
Matching galleries not found. |
404 |