How to Use REST API¶
In this section:
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
The most recent version is v1 which provides such advanced functions as gender, age and emotions recognition.
When starting a new project, you should always use the latest stable version of the API.
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:
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.
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.
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.
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.
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.
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.
If no threshold level is specified, it is set to the default value
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
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
next_page value ‘
/v0/faces/?max_id=12345', you should
GET http://<facenapi_ip:8000/v0/faces/?max_id=12345 to get
the next portion of the results.
FindFace Enterprise Server SDK imposes the following limits.
|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).
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:
codeis a short string in CAPS_AND_UNDERSCORES, usable for automatic decoding.
reasonis a human-readable description of the error and should not be interpreted automatically.
Common Error Codes
||A wrong authentication token or no token has been provided.|
||Some parameters are invalid. This response type has additional attributes ‘param’ and ‘value’ describing which parameter caused the error.|
||The request body doesn’t contain a valid JSON.|
||Your request cannot be processed because some components are experiencing an outage.|