Liveness Detection as Standalone Service

You can harness face liveness detection as a standalone service findface-liveness-api. The service takes a specific number of frames from a video fragment and returns the best quality face, and decimal liveness result 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.

In this section:

Install and Configure findface-liveness-api

To install findface-liveness-api, do the following:

  1. Install the FindFace Security APT repository.

  2. From the APT repository, install the service as such:

    sudo apt update
    sudo apt install findface-liveness-api
  3. If necessary, configure the findface-liveness-api parameters:

    sudo vi /etc/findface-liveness-api.ini
    listen: :18301
    liveness-threshold: 0.75
    fullframe-jpeg-quality: 75
    max-decoded-frames: 30
    min-selected-frames: 10
      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
    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.
    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.
  4. In the findface-extraction-api configuration file, specify the neural network model that provides the liveness standalone service: liveness.alleyn.cpu.fnk/liveness.alleyn.gpu.fnk.

    sudo vi /etc/findface-extraction-api.ini
       liveness: faceattr/liveness.alleyn.cpu.fnk
       liveness: faceattr/liveness.alleyn.gpu.fnk
  5. Start the findface-liveness-api service and enable its autostart.

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

Liveness API Usage

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.8706386,
        "best_face": {
                "liveness": 0.74768883,
                "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