.. _biometric-about: How to Use Multi-Object API --------------------------------------------------------------- .. rubric:: In this section: .. contents:: :local: Endpoint ^^^^^^^^^^^^^^^^^^^ Multi-Object API requests are to be sent to ``http://: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://:18411/docs/`` for the API version /v3. .. _thresholds: 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. .. rubric:: 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 | 400 | | | contains additional attributes ``param`` and ``value`` to indicate which parameters are invalid. | | +------------------------------+--------------------------------------------------------------------------------------------------+------------+ | ``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 | +------------------------------+--------------------------------------------------------------------------------------------------+------------+