Overview

All REST API requests should be sent to https://api.facematica.vocord.ru/v1/.
HTTPS is required to protect user private data.
To make any requests you have to get API_KEY assigned to your account.
Login method /v1/account/login accepts API_KEY and returns access token as result.
All API methods require access token to be presented in 'Authorization' header.
Access token validity period is limited and when expired - clients are supposed to perform login procedure again.

Parameters are represented as a query string i.e. appended to request URL . All responses are in JSON format and UTF-8 encoding.

Examples in methods descriptions illustrate possible method request and its response. To check the examples without writing a code, we recommend using Postman REST client or similar tool and entering request parameters though their GUI.

Please note that you may need to change Token to a valid Token issued to you.

API is separated into sections:

  • Account and authentication
  • Faces and detection
  • Albums and recognition

Account and authentication contains methods to authenticate user and get access token for all the rest API methods.

Faces and detection section provides methods to detect faces on the image, make a match between detected faces. A result of detection (see /v1/face/detect post request) is a set of face descriptors, containing geometric coordinates of face on the photo. Each face is assigned unique identifier (faceid) that can be used to access face info and original image. Detected faces data and original images are stored in the "detection pool" for limited time (72 hours) unless it was added to any album (see "Albums and recognition" section).
Face attributes:

  • "faceid": unique identifier of the face generated by the detect method. faceid refers to any face detected in the Image. Each Image may contain multiple Faces. Each Face is assigned a unique faceid.
  • "img": unique identifier of the image generated by the detect method. All the faces detected on the same image have the same image identifier. Image can be downloaded from detection pool by /v1/face/{faceid}/img get method. Image attributes can be got by /v1/face/{faceid}/img/info get method.
  • "x": x-coordinate of center of the eyes-line,
  • "y": y-coordinate of center of the eyes-line
  • "angle": angle of eyes-line,
  • "width": width of eyes-line,

All the detected faces can be listed by /v1/face/list get method. The method may potentially return a large amount of data. To avoid the problem we support paging (pagesize and page are optional parameters in query string, total-pages is to be returned).
Invoke /v1/face/{faceid}/match post request to match specified face with a list of detected faces. It calculates match-factor for each face from the given set and main face from the URL path.
Typical workflow:

  1. Detect faces on images
  2. Match faces between main face and list of other faces.

Albums and recognition section is to manage albums of faces and search the most matched faces within the albums. This section can be used after detection from ‘Faces and detection’ section.
User can create new album with a specified name and list of detected faces by /v1/album/new post request and add faces later by /v1/album/{name} post request. Album and each face can have additional attributes. Album attributes can be set on creating album or by /v1/album/{name} post request. Face attributes can be added on adding face to the album or later by /v1/album/{name}/{faceid} post request.
It is possible to list all the albums, created by user, by /v1/album/list get method and list all the faces in the album by /v1/album/{name} get method.
Invoke delete method /v1/album/{name}[/faces:*.}] to delete album or specified faces from the album.
The main method of the section is to find most correlative faces from the gallery to a given face. /v1/album/recognize post request matches all the faces from the gallery to a given face from URL and return a list sorted by match factor. List is cut by face count parameter and match-factor threshold.
Typical workflow:

  1. Preparation
    • Detect faces on etalon images.
    • Create album from detected faces or manage an existing one.
  2. Working cycle
    • Detect face on a given image
    • Recognize face with content of the album

Success Response and Error Reporting Success Response is always with HTTP code 200 OK. In case of method fails, it always returns a response with HTTP code other than 200 and a JSON body containing error code and description.

  • ErrorCode is an error code.
  • ErrorMessage is a human-readable description of the error and should not be interpreted automatically. Can be different with the same code depending on method invoked.

Common error codes:
400 (Bad Request ): Some of the parameters are invalid. This response ErrorMessage describes which parameter caused the error.
401 (Unauthorized): Wrong authentication token or no token at all is provided.

Storage quotas (per account): • Number of albums 100

  • Number of faces stored on server 50000

Limits:

  • Image formats JPEG, PNG
  • Maximum photo file size 10 MB
  • Maximum photo resolution 4,000 pixels on the biggest side
  • Minimal distance between eyes 25 pixels
  • Maximum number of detected faces on a single photo Unlimited

Read the full API