How to Use Multi-Object API

In this section:

Endpoint

Multi-Object API requests are to be sent to http://<sf-api_IP_address>:18411/. API requests are executed by the 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, v3 in /v3/detect/).

There are versions v2 and v3 at the moment. The most recent version is v3.

Tip

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

API Objects

Multi-Object API operates the multiple objects that represent detected physical objects. The most basic are:

  • face – a human face

  • body – a human silhouette

  • car – a vehicle

Note

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

Note

Different images of the same object are considered to be different API objects.

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 multi-object 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://<sf-api_IP_address>:18411/docs/ for the API version /v3.

Limits

FindFace Server imposes the following limits.

Limit

Value

Image formats

JPG, PNG, WEBP, BMP

Maximum photo file size

To be configured via the sf-api configuration file.

Minimal size of an object

50x50 pixels

Maximum number of detected objects 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.

  • 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 an object 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 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 multi-object database not available.

503

CACHE_ERROR

Memcached not available.

503

NOT_FOUND

Matching objects not found.

404

NOT_IMPLEMENTED

This functionality not implemented.

501

GALLERY_NOT_FOUND

Matching galleries not found.

404