How to Use REST API

In this section:

Endpoint

All REST API requests should be sent to http://<facenapi_ip>:8000/v1/.

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 should be specified in the request path (for example, v1 in /v1/detect/).

The most recent version is v1 which provides such advanced functions as gender, age and emotions recognition.

Note

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

Authentication

All API methods require a simple token-based HTTP Authentication. In order to authenticate, you should put the word “Token” and your token key into the Authorization HTTP header, separated by a whitespace:

Note

To learn how to create a token, consult Create Authentication Token.

Authorization: Token yfT8ftheVqnDLS3Q0yCiTH3E8YY_cm4p

All requests that fail to provide a valid authentication token will result in a HTTP 401 Unauthorized response.

Common Object Types

Face

Represents a human face. Note that it might be several faces on a single photo. Different photos of the same person as also considered to be different faces.

• "id" (number): unique identifier of the face generated by API.
• "timestamp" (string): time of face object creation as ISO8601 string.
• "photo" (string): URL of file name of a photo that had been used to create the face object.
• "photo_hash" (string): Hash of the original photo. Note that identical photos will always have the same hash, and different photos will most certainly have different hashes. Don’t interpret this value and don’t make assumptions about particular hash function used for hash calculation.
• "thumbnail" (string): URL of face thumbnail stored on FindFace servers.
• "x1" (number): x coordinate of the top-left corner of face’s bounding box on the original photo.
• "y1" (number): y coordinate of the top-left corner of face’s bounding box on the original photo.
• "x2" (number): x coordinate of the bottom-right corner of face’s bounding box on the original photo.
• "y2" (number): y coordinate of the bottom-right corner of face’s bounding box on the original photo.
• "meta" (string): metadata string that you can use to store any information associated with the face.
• "galleries" (string[]): array of galleries names that have this face.

Bounding Box (bbox)

Represents a rectangle on a photo. Usually used as a face’s bounding box. May be specified in two ways:

• Separated coordinates:

  • "x1" (number): x coordinate of the top-left corner of the bounding box.
  • "y1" (number): y coordinate of the top-left corner of the bounding box.
  • "x2" (number): x coordinate of the bottom-right corner of the bounding box.
  • "y2" (number): y coordinate of the bottom-right corner of the bounding box.

• Array of coordinates [x1, y1, x2, y2]

The API methods accept both formats, but always return bbox as a JSON dictionary.

Note that in some case the coordinates might be outside photo dimensions, including negative values.

Parameters Format

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

• application/json: parameters are represented by a JSON contained in the body.
• application/x-www-form-urlencoded: parameters are represented by form field names and values.
• multipart/form-data: parameters are encoded into separate parts. This way supports uploading a photo image file in the same request.
• query string: parameters are appended to request URI. When passing parameters in a query string, complex structures (such as bboxes) should be encoded in JSON.

There are two ways of specifying a photo image file:

• As a publicly accessible URL.
• Included in a request as part of multipart form.

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://<facenapi_ip>:8000/v1/docs/v1/overview.html for the API version /v1.

Confidence Thresholds

For some methods you need to specify a threshold for verification or identification confidence. The higher is the threshold, the less are chances that a wrong person will be positively verified or identified, however, some valid photos may also fail verification.

There are 4 pre-defined threshold levels:

• Strict (0.7834): used for applications where a chance of misidentification should be minimized. This level corresponds to False Accept Rate (FAR) of 1e-5 on our test dataset.
• Medium (0.6616): balances low probability of misidentification and inability to identify a valid person. Corresponds to 1e-3 FAR on our test dataset.
• Low (0.5690): used when it’s important to maximize the verification or identification rate, and misidentification does not cause severe consequences. Corresponds to 1e-1 FAR on our test dataset.
• None (0): use when you need to calculate similarity of different persons or find similar people rather than verify identity.

You can also specify your own threshold level from 0 to 1, depending on your environment and needs.

Note

If no threshold level is specified, it is set to the default value 0.75.

Pagination

Some methods (such as GET /faces/ and GET /meta/) may potentially return thouthands and hundreds of thouthands results. To avoid problems associated with such large amounts, we have introduced pagination.

Methods that support pagination return two more parameters in addition to a list of results:

• prev_page: URL to the previous page (path and query only)
• next_page: URL to the next page (path and query portion only)

For example, if GET http://<facenapi_ip>:8000/v0/faces/ has returned the next_page value ‘/v0/faces/?max_id=12345', you should request GET http://<facenapi_ip:8000/v0/faces/?max_id=12345 to get the next portion of the results.

Limits

FindFace Enterprise Server SDK imposes the following limits.

Limit	Value
Image formats	JPEG, PNG, WEBP
Maximum photo file size	10 MB
Minimal size of a face	50x50 pixels
Maximum number of detected faces on a single photo	Unlimited

Additionally, the URL provided to the API to fetch an image should 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 status:

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

Common Error Codes

Error code	Description
AUTH_FAILED	A wrong authentication token or no token has been provided.
BAD_PARAM	Some parameters are invalid. This response type has additional attributes ‘param’ and ‘value’ describing which parameter caused the error.
MALFORMED_JSON	The request body doesn’t contain a valid JSON.
SERVICE_UNAVAILABLE	Your request cannot be processed because some components are experiencing an outage.