Liveness Detection as Standalone Service

Configure `liveness-api`

To configure the liveness-api component, do the following:

Create a default liveness-api.yaml configuration file (e.g., into the /opt/ffserver/configs directory).

docker run --rm -ti --name liveness-api-cfg \
    docker.int.ntl/ntech/universe/liveness-api:ffserver-11.240325 \
    --config-template > /opt/ffserver/configs/liveness-api.yaml

You can configure the liveness-api parameters according to your needs in the /opt/ffserver/configs/liveness-api.yaml configuration file. You can find its default content here. Enable liveness recognition in the /opt/ffserver/configs/extraction-api.yaml configuration file by specifying the extraction model in the face_liveness section. See Enable Face and Face Attribute Recognition.

When configuring liveness-api, refer to the following parameters:

Command line flags	Type	Description
`-attributes`	value	Array of attributes to extract.
`-config`	string	Path to config file
`-config-template`		Output config template and exit.
`-debug`		Debug.
`-extraction-api-extraction-api`	string	Extraction API address (default `http://127.0.0.1:18666`).
`-extraction-api-request-batch-size`	int	Extraction API request batch size (default 16).
`-extraction-api-timeouts-connect`	duration	extraction-api-timeouts-connect (default 5s).
`-extraction-api-timeouts-idle-connection`	duration	extraction-api-timeouts-idle-connection (default 10s).
`-extraction-api-timeouts-overall`	duration	extraction-api-timeouts-overall (default 35s).
`-extraction-api-timeouts-response-header`	duration	extraction-api-timeouts-response-header (default 30s).
`-fullframe-jpeg-quality`	int	JPEG quality of full frames in the `photo` field (default 75).
`-help`		Print help information.
`-limits-video-fps`	float	Maximum video frames per second (default 60).
`-limits-video-height-px`	int	Maximum video height in px (default 1080).
`-limits-video-length-sec`	float	Maximum video length in seconds (default 60).
`-limits-video-size`	int	Maximum size of video supplied in request body, bytes. (default 10485760).
`-limits-video-width-px`	int	Maximum video width in pixels (default 1920)
`-listen`	string	IP:port to listen on (default `:18301`).
`-liveness-threshold`	float	Liveness threshold (default 0.994).
`-max-decoded-frames`	int	Finish decoding after reaching the specified number of frames (default 30).
`-mf-selector`	string	Service behavior upon having multiple faces in the video frame: `reject` - reject this frame, `biggest` - use the biggest face for liveness detection. (default `reject`).
`-min-selected-frames`	int	The minimum number of final frames successfully passed through decoding and liveness extraction. Must be equal or less than `max-decoded-frames`. (default 10).
`-processing-script`	string	Path to LUA file with processing_script function (default `processing_score.lua`).
`-reject-ignore-secondary-faces-by-proportion`	float	Proportion of the secondary faces for them to be ignored.
`-sf-api-sf-api`	string	SF API address (default `http://127.0.0.1:18411`).
`-sf-api-timeouts-connect`	duration	sf-api-timeouts-connect (default 5s).
`-sf-api-timeouts-idle-connection`	duration	sf-api-timeouts-idle-connection (default 10s).
`-sf-api-timeouts-overall`	duration	sf-api-timeouts-overall (default 35s).
`-sf-api-timeouts-response-header`	duration	sf-api-timeouts-response-header (default 30s).

The format of environment variable for flag -my-flag is CFG_MY_FLAG.

Priority:

Defaults from source code (lowest priority).
Configuration file.
Environment variables.
Command line.

Note

When working with processing_<attribute>.lua don’t forget to get the appropriate attribute by setting it in the configuration file in the attributes section.

The default processing_score.lua file describes the logic of choosing the best face:

function process(candidates)

    local best_frame_idx = nil
    local best_score = nil
    for idx, candidate in pairs(candidates) do
        local score = candidate.score
        if (best_frame_idx == nil) or (best_score < score) then
            best_score = score
            best_frame_idx = idx
        end
    end

    return best_frame_idx
end

HTTP API Requests to `liveness-api`

To interact with the liveness-api service, use HTTP API requests to http://liveness-api:18301/.

POST /v1/video-liveness

This method determines liveness by video.

Query string parameters:

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

Request Body:

Contains a video file.

Responses with Common Codes:

Code	Description
200	OK. Returns `application/json`.
400	Bad Request.
405	Invalid input.
406	Not Acceptable.
500	Internal Server Error.

Example

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
   "alive":true,
   "average_liveness":0.9521886,
   "best_face":{
      "liveness":0.9557304,
      "quality":0.91568387,
      "bbox":{
         "left":138,
         "top":172,
         "right":363,
         "bottom":468
      },
      "detection_id":"btfiva1o8cjc1k44q1vg",
      "photo":"/9j/2wCEAAgGBgcGBQgHBwcJ...",
      "normalized":"iVBORw0KGgoAAAANSUU...",
      "frame_no":14,
      "frame_ts":0.56
   }
}

Liveness Detection as Standalone Service

Configure liveness-api

HTTP API Requests to liveness-api

Configure `liveness-api`

HTTP API Requests to `liveness-api`