Liveness Detection as Standalone Service

Besides the integrated 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 authentication.

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

In this section:

Install and Configure findface-liveness-api

To install the service standalone, install the FindFace Multi APT repository and execute the following commands:

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:

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
  request-batch-size: 16
    connect: 5s
    response_header: 30s
    overall: 35s
    idle_connection: 10s
    connect: 5s
    response_header: 30s
     overall: 35s
    idle_connection: 10s
  video-size: 10485760
  video-length-sec: 60
  video-fps: 30
  video-width-px: 1920
  video-height-px: 1080




JPEG quality of full frames in the photo field.


Finish decoding after reaching the specified number of frames.


The minimum number of final frames successfully passed through decoding and liveness extraction. Must be equal or less than max-decoded-frames.


Service behavior upon having multiple faces in the video frame: reject - reject this frame, biggest - use the biggest face for liveness detection.

extraction-api -> request-batch-size

Batch size for liveness extraction.

limits -> video-size

Maximum video size, bytes.

limits -> video-length-sec

Maximum video length, seconds.

limits -> video-fps

Maximum video FPS.

limits -> video-width-px

Maximum video width, pixels.

limits -> video-height-px

Maximum video height, pixels.

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

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.



curl -i -X POST \
  '' \
  -H 'Content-Type: video/mp4' \
  --data-binary '@/home/my_video.mp4'


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