RESTful JSON API VideoLivenessDetection

Performs liveness detection on a video.

When we receive a video for liveness detection, we perform a passive liveness detection on a bunch of equidistant sampled frames of the video. A decision is made, when one of the breaking conditions is reached:

A minimum number of live decisions (currently 7) has been made ⇒ the video is considered live.
A minimum number of fake decisions (currently 7) has been made ⇒ the video is considered to be a fake.
A maximum number of failures has been reached (currently 5) or not enough frames are available ⇒ the process is aborted with an FailureToAcquire error.

Request

POST /api/v1/videolivenessdetection

Request Body

Content type: application/json

{
  "video": "string"
}

The VideoLivenessDetection request object has a single field:

video: The binary input video data, base64 encoded.

Request Headers

This API requires a valid JWT in the Authorization request header and accepts an optional reference number.

Authorization	Required Bearer authentication. Please refer to BWS API Authentication for a description of how to provide a valid JWT here.
Reference-Number	Optional, client specific reference number, which will be added to the BWS bookkeeping as well as to the response header. You typically use this reference to link the resulting BWS bookkeeping entries with your logs.

Response

Response Body

Content type: application/json

{
  "status": "SUCCEEDED",
  "errors": [
    {
      "errorCode": "string",
      "message": "string"
    }
  ],
  "imageProperties": [
    {
      "rotated": 0,
      "faces": [
        {
          "leftEye": {
            "x": 0,
            "y": 0
          },
          "rightEye": {
            "x": 0,
            "y": 0
          },
          "textureLivenessScore": 0,
          "motionLivenessScore": 0,
          "movementDirection": 0
        }
      ],
      "qualityScore": 0,
      "qualityAssessments": [
        {
          "check": "string",
          "score": 0,
          "message": "string"
        }
      ],
      "frameNumber": 0
    }
  ],
  "live": true,
  "livenessScore": 0
}

On success the API returns a LivenessDetection response object with the fields as follows:

status: The status of the BWS job that processed the request. The following fields are typically only set, when the job has succeeded.
errors: A list of errors that might have occurred while the request has been processed.
imageProperties: The calculated image properties for each of the processed frames.
live: The liveness decision made by BWS. If this field is set to true, the provided video is supposed to be recorded from a live person. No errors are reported in this case. When this field is set to false, there is at least one error reported that explains, why the provided video is supposed not to be recorded from a live person.
livenessScore: An informative liveness score (a value between 0.0 and 1.0) that reflects the confidence level of the live decision. The higher the score, the more likely the person is a live person. If this score is exactly 0.0, it has not been calculated and an error has been be reported.
The liveness score is the average of all calculated passive and active liveness detection scores. For the liveness decision, the individual passive and active liveness detection scores are used.

BWS Errors

In case that the live field is set to false, at least one of the following errors is reported in the errors field:

FailureToAcquire: The video does not contain enough images with exactly one suitable face in it.
RejectedByPassiveLiveDetection: A minimum number of frames in this video indicate, that video is not recorded from a live person.

HTTP Status Codes

The call returns one of the standard HTTP status codes, e.g.:

200 (OK): The response body contains the LivenessDetection response object as described above.
400 (Bad Request): The call failed, typically due to an invalid argument. The response body contains a JSON object with the reported gRPC error code and message.
401 (Unauthorized): The request does not have valid authentication credentials for the operation.
408 (Request Timeout): Client application cancelled the request.
500 (Internal Server Error): Server experienced some unexpected behaviour.
503 (Service Unavailable): The service is currently unavailable. This is most likely a transient condition and may be corrected by retrying with a backoff.

Response Headers

All successful BWS calls return a response header containing additional information about the request:

jobid	The Job-ID (a GUID) that has been assigned to this BWS call.
bws-version	The version of the BWS gRPC service.
reference-number	An optional reference number as provided in the request header.
date	The timestamp when the request has been received at the server.
...	Other headers that might have been added by the server (NGINX, Kestrel, ...) that was handling the request.

Example:

Here is a short example of how to call into the VideoLivenessDetection RESTful JSON API using a video loaded from a file.

Please refer to BWS API Authentication for a description of the methods CreateAuthenticatedClient and GenerateToken.

This sample code makes use of some C# JSON data transfer objects, which you can find in the BwsJsonDto.cs source file.

using HttpClient httpClient = CreateAuthenticatedClient(new Uri(options.Host), GenerateToken(options.ClientId, options.Key));
var request = new VideoLivenessDetectionRequest { Video = Convert.ToBase64String(File.ReadAllBytes(vidoeFile)) };
var response = await httpClient.PostAsync("/api/v1/videolivenessdetection", JsonContent.Create(request));
if (response.IsSuccessStatusCode)
{
    var responseContent = await response.Content.ReadFromJsonAsync<LivenessDetectionResponse>();
    // ...
    Console.WriteLine($"This was live: {responseContent.Live} (confidence: {responseContent.LivenessScore})");
}
else
{
    Console.WriteLine($"Server response: {response.StatusCode}");
}

todo

todo

Browse docs