drawing

T5-Liveness Detection Service (LDS)

Version 1.1
This document is intended for technical developer who are integrating the T5-LDS for performing liveness detection. It describes the API along with interface and packet structure to be used by the clients communicating with the Tech5 T5-LDS.

Disclaimers

The information contained in this document is the proprietary and exclusive property of Tech5 except as otherwise indicated. No part of this document, in whole or in part, may be reproduced, stored, transmitted, or used for design purposes without the prior written permission from Tech5.

The information contained in this document is subject to change without notice. The information in this document is provided for informational purposes only. Tech5 specifically disclaims all warranties, express or limited, including, but not limited, to the implied warranty of merchant-ability and fitness for a particular purpose, except as provided for in a separate software license agreement.

Privacy Information

This document may contain information of a sensitive nature. This information should not be given to individuals other than those who are involved in the T5-LDS development or integration.

Contact : support@tech5-sa.com

Overview

Tech5 liveness detection service (LDS) is designed to serve customers who have limitations on using Tech5 Liveness iOS and Android SDK products.

Introduction

LDS is a REST API based service which takes a photo OR video clip + predefined challenge code as input. The service processes the request to confirm on of the two LD checks defined below.

In the context of the intended uses cases the LDS will serve the following purpose:

  1. Passive Liveness Detection (PLD): Given a single shot/photo the LDS will check for common anti spoofing attacks. This approach is less accurate but is fast and requires low payload. If successful the LDS will return the template which can be used for matching.
  2. Active Liveness Detection (ALD) : The basic principle is based on a challenge response concept. A video with a person performing predetermined challenge (like look left) is passed to LDS. The LDS will confirm if the person did complete the challenge. The algorithm will also check for common anti spoofing attacks. This approach is more accurate but slow and higher payload. The technology behind the service uses a highly accurate Tech5 trained Neural Network and algorithm. If the subject successfully completed the challenge, LDS will also returns one template from the clip which can be used for verifying if the same person is in the various challenges.

REST API

Active liveness detection (ALD)

=== REQUEST ===
POST /v1/lds?challenge=[LL, LR, LU, LD, RL, RR]&fq=jpeg_quality&tid=transaction_id HTTP/1.1
Content-Type: video/[avi, flv, wmv, mp4, mov, etc]
Content-Length: length in bytes

[VIDEO RAW DATA]

=== RESPONSE ===
HTTP [200 OK, 400 Bad request, 500 Internal error, etc]
Content-Type: application/json
Content-Length: length in bytes
{
“status”: [“PASSED”, “FAILED”]
“failReason”: [“FACE_NOT_FOUND”, “TOO_MANY_FACES”, “TOO_FAST”, “TOO_LONG”, “WRONG_DIRECTION”, “CHALLENGE_INCOMPLETE”]
“failFrame”: frame_number
“bestFrame”: frame_number
“croppedFace”: BASE64 encoded JPEG image
“tid”: transaction_id
}

Query parameters description:

Parameter Meaning
challenge One of challenge codes described below
fq CroppedFace JPEG quality in range [0-100]. Optional. Defaults to 75
tid Transaction ID. Optional

Challenge Codes:

Code Meaning
LL Look Left
LR Look Right
LU Look Up
LD Look Down
RL Roll Left
RR Roll Right

Request example

Request can be simulated using curl tool:

curl -H "Content-type: video/mp4" --request POST --data-binary "@/data/video2.mp4" "http://lds_server/v1/lds?challenge=LL&fq=75&tid=8001020"

Possible response:

HTTP 200 OK
Content-Type: application/json
Content-Length: 270910
{
"status": "PASSED"
"failReason": ""
"failFrame": "0"
"bestFrame": "27"
"croppedFace": "UEsDBBQA2hBkZXNrdG9 .. AAQABADkAAAC+AAAAAAA="
"tid": "8001020"
}

Passive liveness detection (PLD)

=== REQUEST ===
POST /v1/lds/passive?tid=transaction_id HTTP/1.1
Content-Type: video/[avi, flv, wmv, mp4, mov, etc]
Content-Length: length in bytes

[VIDEO RAW DATA]

=== RESPONSE ===
HTTP [200 OK, 400 Bad request, 500 Internal error, etc]
Content-Type: application/json
Content-Length: length in bytes

{
“frameSpoofing”: [
{
“spoofing”: spoofing_value
“errorCode”: error_code,
“errorMessage”: error_message
},

],
“videoSpoofing”: spoofing_value
“tid”: transaction_id
}

Query parameters description:

Parameter Meaning
tid Transaction ID. Optional

Response description:

Response is a JSON object consisting of following fields:

Field Description
frameSpoofing Array of objects corresponding to each frame of input video. Each item is either { "spoofing": spoofing_value } or { "errorCode": error_code, "errorMessage": error_message } object. Error have one of following values 1 - FACE_NOT_FOUND; 2 - TOO_MANY_FACES
videoSpoofing Overall spoofing value for entire video
tid Transaction ID. Optional

Request example

Request can be simulated using curl tool:

curl -H "Content-type: video/mp4" --request POST --data-binary "@/data/video2.mp4" "http://lds_server/v1/lds/passive?tid=8001020"

Possible response:

HTTP 200 OK
Content-Type: application/json
Content-Length: 3910
{
  "frameSpoofing": [
    {
      "spoofing": 0.12453067302703857
    },
    {
      "errorCode": 1,
      "errorMessage": "FACE_NOT_FOUND"
    },
    {
      "spoofing": 0.12465859949588776
    },
    {
      "spoofing": 0.1268700808286667
    },
    ...
    {
      "spoofing": 0.1268700808286667
    }
  ],
  "videoSpoofing": 0.12340638041496277
  "tid": "8001020"
}

Video Specification

Requirements for the video:
Min number of frames - 5
Max length - 3.5 s
Min resolution: 720 x 576
Supported codecs and containers - ffmpeg lib supported (H.264, H.265, etc.; avi, mpeg4, etc.)

Sample ALD scenario using LDS

DeviceCustomer ServerTech5LDSMBAPInitiateSend Challenge CodeShow instructions, record video, crop & compress. Send clip orstream video to Customer ServerSend video clipResize and compress if requiredSend video clip + challenge codeProcess clipPass/Fail & cropped imageloop[ Every challenge ]Cropped faces from challenges and final photoConfirm same person in all clips and final photoFinal photoor template and ID for authenticationAuthentication passed or failedDeviceCustomer ServerTech5LDSMBAP

Note: The cropped faces returned in each challenge can be used to make sure the person in each challenge is the same you would like to authenticate or enroll