.. _liveness-api:

Liveness Detection as Standalone Service
======================================================

.. seealso::
   :ref:`liveness`

Besides the :ref:`integrated <liveness>` anti-spoofing system that distinguishes a live face from a face image, FindFace Multi provides an API-based face liveness detection service ``findface-liveness-api``. 

The ``findface-liveness-api`` service takes a specific number of frames from a provided video fragment and returns the best quality face, along with a decimal liveness result for it, averaged across the taken frames.  If configured, the service can also return full-frame and normalized face images and save the detection result in the ``findface-sf-api`` cache, returning ``detection_id``.

The ``findface-liveness-api`` service is automatically installed and activated, as FindFace Multi requires it for face-based :ref:`authentication <authentication>`.  

You can install and use the ``findface-liveness-api`` service standalone, apart from FindFace Multi. This is what this section is about. 


.. rubric:: In this section:

.. contents::
   :local:

Install and Configure ``findface-liveness-api``
--------------------------------------------------

To install the service standalone, install the FindFace Multi :ref:`APT repository <install-repo>` and execute the following commands: 

.. code::  

   sudo apt update
   sudo apt install findface-liveness-api

You can configure the ``findface-liveness-api`` parameters in the ``/etc/findface-liveness-api.ini`` configuration file:

.. code::

   sudo vi /etc/findface-liveness-api.ini

   listen: :18301
   liveness-threshold: 0.95
   fullframe-jpeg-quality: 75
   max-decoded-frames: 30
   min-selected-frames: 10
   mf-selector: reject
   extraction-api:
     request-batch-size: 16
     timeouts:
       connect: 5s
       response_header: 30s
       overall: 35s
       idle_connection: 10s
     extraction-api: http://127.0.0.1:18666
   sf-api:
     timeouts:
       connect: 5s
       response_header: 30s
        overall: 35s
       idle_connection: 10s
     sf-api: http://127.0.0.1:18411
   limits:
     video-size: 10485760
     video-length-sec: 60
     video-fps: 30
     video-width-px: 1920
     video-height-px: 1080

+----------------------------+----------------------------------------------------------------------------------------------+
| Parameter                  | Description                                                                                  |
+============================+==============================================================================================+
| ``fullframe-jpeg-quality`` | JPEG quality of full frames in the ``photo`` field.                                          |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``max-decoded-frames``     | Finish decoding after reaching the specified number of frames.                               |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``min-selected-frames``    | The minimum number of final frames successfully passed                                       |
|                            | through decoding and liveness extraction. Must be equal or less than ``max-decoded-frames``. |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``mf-selector``            | Service behavior upon having multiple faces in the video frame: ``reject`` - reject this     |
|                            | frame, ``biggest`` - use the biggest face for liveness detection.                            |
+----------------------------+----------------------------------------------------------------------------------------------+             
| ``extraction-api`` ->      | Batch size for liveness extraction.                                                          |
| ``request-batch-size``     |                                                                                              |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``limits`` ->              | Maximum video size, bytes.                                                                   |
| ``video-size``             |                                                                                              |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``limits`` ->              | Maximum video length, seconds.                                                               | 
| ``video-length-sec``       |                                                                                              |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``limits`` ->              | Maximum video FPS.                                                                           |
| ``video-fps``              |                                                                                              |
+----------------------------+----------------------------------------------------------------------------------------------+
| ``limits`` ->              | Maximum video width, pixels.                                                                 |
| ``video-width-px``         |                                                                                              | 
+----------------------------+----------------------------------------------------------------------------------------------+
| ``limits`` ->              | Maximum video height, pixels.                                                                |
| ``video-height-px``        |                                                                                              | 
+----------------------------+----------------------------------------------------------------------------------------------+


To start the ``findface-liveness-api`` service and enable its autostart, execute:

.. code::

   sudo systemctl start findface-liveness-api.service && sudo systemctl enable findface-liveness-api.service



HTTP API Requests to ``findface-liveness-api``
------------------------------------------------

To interact with the ``findface-liveness-api`` service, use HTTP API requests. In the example below, the POST request is sent with the following optional parameters:

* ``return_detection`` (``default=False``): save the best face in the ``findface-sf-api`` cache and return its ``detection_id``.
* ``return_normalized`` (``default=False``): return the face normalized image in the ``normalized`` field.
* ``return_photo`` (``default=False``): return the full frame in the ``photo`` field.

.. rubric:: Example

.. rubric:: Request

.. code::

   curl -i -X POST \
     'http://127.0.0.1:18301/v1/video-liveness?return_detection=true&return_normalized=true&return_photo=true' \
     -H 'Content-Type: video/mp4' \
     --data-binary '@/home/my_video.mp4'

.. rubric:: Response

.. code::

   HTTP/1.1 100 Continue
   HTTP/1.1 200 OK
   Content-Type: application/json
   X-Request-Id: LA:WSP2NcHc
   Date: Mon, 07 Sep 2020 15:30:05 GMT
   Transfer-Encoding: chunked
   {
           "alive": true,
           "average_liveness": 0.9706386,
           "best_face": {
                   "liveness": 0.97768883,
                   "quality": 0.89638597,
                   "bbox": {
                           "left": 0,
                           "top": 578,
                           "right": 307,
                           "bottom": 1154
                   },
                   "detection_id": "btb53vbp688s1njt3bv0",
                   "photo": "/9j/2wCEAAgGBgcGBQgHBwcJ...",
                   "normalized": "iVBORw0KGgoAAAANSUhEU...",
                   "frame_no": 1,
                   "frame_ts": 0.033275817
           }
   }



.. seealso::
   :ref:`deactivate-liveness-api`