Liveness Detection as Standalone Service

See also

Real-time Face Liveness Detection

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
   
   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.
   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
   
   extractors:
     ...
     models:
      ...
      liveness: faceattr/liveness.alleyn.cpu.fnk
      ...
     ...
   
   extractors:
     ...
     models:
      ...
      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.

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