Introduction

This service is a backport API platform 5 (api version /6/) to api platform 4 (api version /5/).

Warning

Several resources differ from original Luna API platform 4.

See the differences here:

Backport

“To backport” means to retroactively supply a fix or a new feature to a previous version of a software product at the same time (or after) supplying it to the current version.

In LUNA PLATFORM, Backport is a mechanism of the new platform version mimicry to the older one by adding a “smart proxy@” to the user-end services (Luna API, Luna Sender).

The differences between the created requests for the two versions are listed in this document.

Temporary attributes

One of the greatest differences between LUNA PLATFORM 4 and LUNA PLATFORM 5 are attributes.

  • Attributes in LP4 have no TTL. Attributes are stored in the database and can be linked to a face using “attribute_id”.

  • Attributes in LP5 have TTL and are deleted after the TTL is expired. The temporary attribute “attribute_id” exists only for the temporary attribute and it is removed with this attribute when its TTL expires.

When an attribute is used to create a face in LP5, the attribute data is copied to the Faces database without the “attribute_id”. The face_id of the created face can be conditionally used instead of attribute_id. Note that face_id and attribute_id are different IDs.

The lifetime of temporary attributes can be configured using the ATTRIBUTES_STORAGE_POLICY.MAX_TTL setting in the LUNA Backport 4 configuration file for all the resources working with temporary attributes.

General differences

The general differences are listed above:

  1. The current versions for LUNA PLATFORM services are returned on the request to the /version resource. For example, the versions of the following services are returned:

    1. “luna-faces”

    2. “luna-events”

    3. “luna-image-store”

    4. “luna-python-matcher” or “luna-matcher-proxy”

    5. “luna-tasks”

    6. “luna-handlers”

    7. “luna-api”

    8. “LUNA PLATFORM”

    9. “luna-backport4” - the current service

  2. Resources changelog:

    • Resource /attributes/count is available without any query parameters and does not support accounting. The resource works with temporary attributes.

    • Resource /attributes on method GET: attribute_ids query parameter is allowed instead of page, page_size, time__lt and time__gte query parameters. Thus you can get attributes by their IDs not by filters. The resource works with temporary attributes.

    • Resource /attributes/<attribute_id> on methods GET, HEAD, DELETE and resource /attributes/<attribute_id>/samples on method GET interact with temporary attributes and return attribute data if the attribute TTL has not expired. Otherwise, the “Not found” error is returned. If you already used the attribute to create a face, use the “face_id” to receive the attribute data. In this case, the attribute_id from the request is equal to face_id.

    • Resource /faces enables you to create more than one face with the same attribute_id.

    • Resource /faces/<face_id> on method DELETE enables you to remove face without removing its attribute.

    • Resource /faces/<face_id> on method PATCH enables you to patch attribute of the face making the first request to patch event_id, external_id, user_data, avatar (if required) and the second request to patch attribute (if required). If face attribute_id is to be changed, the service will try to patch it with temporary attribute data if the temporary attribute exists. Otherwise, the service tries to patch it with attribute data from the face with face_id = attribute_id.

    • Resource /events/stats on method POST: “attribute_id” usage in “filters” object was prohibited as this field is no longer stored in the database. The response with the 403 status code will be returned.

    • Attribute_id in events is not null and is equal to face_id for back compatibility.

    • GC task is unavailable because all the attributes are temporary and will be removed automatically. Status code 400 is returned on a request to the /tasks/gc resource.

    • The column attribute_id is not added to the report of the Reporter task and this column is ignored if specified in the request. Columns top_similar_face_id, top_similar_face_list, top_similar_face_similarity are replaced by the top_match column in the report if any of these columns is passed in the reporter task request.

    • Linker task always creates new faces from events and ignores faces created during the event processing request.

    • Resource /matcher does not check the presence of provided faces thus error FacesNotFound is never returned. If the user has specified a non-existent candidate of type “faces”, no error will be reported, and no actual matching against that face will be made.

    • Resource /matcher checks whether reference with type attribute has the ID of face attribute or the ID of temporary attribute and performs type substitution. Hence it provides sending references for matching in the way it was done in the previous version.

    • Resource /matcher takes matching limits into account. By default, the maximum number of references or candidates is limited to 30. If you need to overcome these limits, configure REFERENCE_LIMIT and CANDIDATES_LIMIT.

    • Resource /ws has been added. There was no /ws resource in the LUNA PLATFORM 4 API as it was a separate resource of the Sender service. This added resource is similar to the Sender service resource, except that attribute_id of candidates faces is equal to face_id.

    • Resource /handlers returns the error “Invalid handler with id {handler_id}”, if the handler was created in the LUNA PLATFORM 5 API and is not supported in LUNA Backport 4.

Luna Backport 4 documentation

Luna Backport 4 is a facial recognition web service. It provides RESTful interface for interaction with other LUNA PLATFORM services.

Using the API service you can solve the following problems:

  • Images processing and analysis:

    • face detection in photos;

    • face attributes (age, gender, ethnicity) and face properties (head pose, emotions, gaze direction, eyes attributes, mouth attributes) estimation;

  • Search for similar faces in the database;

  • Storage of the received face attributes in databases;

  • Creation of lists to search in;

  • Statistics gathering;

  • Flexible request management to meet user data processing requirements.