Additional Information

Confidence Thresholds

Some methods allow specifying threshold for verification or identification confidence. The higher is the threshold, the less are chance that the wrong person will be incorrectly verified or identified, but also some valid photos may fail verification.

We have pre-defined three threshold levels:

  • Strict (0.7834): use 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 chance of misidentification and inability to identify a valid person. Corresponds to 1e-3 FAR on our test dataset.
  • Low (0.5690): use when it's important to maximize verification or identification rate, but 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 unique environment and needs.

Pagination

Some methods (such as GET /faces/ and GET /meta/) may potentially return thouthends and hundreds of thouthends 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 https://api.findface.pro/v0/faces/ returned next_page value of /v0/faces/?max_id=12345, you should request GET https://api.findface.pro/v0/faces/?max_id=12345 to get the next portion of the results.

Limits

There are several limits imposed by the FindFace Cloud API.

Limit Value
Image formats JPEG, PNG, WEBP
Maximum photo file size 10 MB
Maximum photo resolution 4,000 pixels on the biggest side
Minimal size of a face 50x50 pixels
Maximum number of detected faces on a single photo Unlimited
Maximum number of galleries per account 50

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

Should you feel uncomfortable with any of these limits, please let us know and we will try to lift the limit for you.

Error Reporting

If a method fails, it always returns a response with HTTP code other than 200 and a JSON body containing error description. Error body always has 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 Wrong authentication token or no token at all is provided.
BAD_PARAM Some of the parameters are invalid. This response type has additional attributes called param and value describing which parameter caused the error.
MALFORMED_JSON Request body doesn't contain a valid JSON
SERVICE_UNAVAILABLE Your request cannot be processed because some parts of the cloud are experiencing an outage.