Liveness Detection as Standalone Service

See also

Real-time Face Liveness Detection

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
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 -> 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.

Example

Request

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'

Response

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
        }
}

See also

Deactivate findface-liveness-api installed with FindFace Multi