Performs liveness detection on one or two live images. Depending on the number of live images and the tags provided in the call, different versions of our liveness detection will be executed:
One image: Only passive liveness detection will be performed. Due to the limitation to a single image, only the texture based liveness detection can be used to make a decision.
Two images: Passive and active liveness detection will be performed. Beside of the texture based liveness detection on each of the provided images a motion based 3D detection on each two consecutive images is executed. All decisions must indicate a live person to finally declare the entire call as live.
Two images with tagged second image: Passive and active liveness detection will be performed. Additionally a challenge-response mechanism is applied. As we have a motion direction calculated for the face found in the second image, we can check whether this is the same direction as demanded by the tags, i.e. whether the head moved up, down, left or right as requested. Also refer to the Liveness Detection Modes.
POST /api/v1/livenessdetection
Content type: application/json
{
"liveImages": [
{
"image": "string",
"tags": [
"string"
]
}
]
}The LivenessDetection request object has a single field:
liveImages
The maximum API request size is 50 MB.
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. |
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:
statuserrorsimagePropertieslivetrue, the provided images are 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 images are not supposed to be recorded from a live person.
livenessScoreAn 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.
In case that the live field is set to false, at least one of the following errors is reported in the errors field:
FullyVisibleFace quality check results.The call returns one of the standard HTTP status codes, e.g.:
code and message.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. |
Here is a short example of how to call into the LivenessDetection RESTful JSON API using live images loaded from files.
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 LivenessDetectionRequest();
foreach (string file in options.Files)
{
request.LiveImages.Add(new ImageData { Image = Convert.ToBase64String(File.ReadAllBytes(file)) });
}
var response = await httpClient.PostAsync("/api/v1/livenessdetection", 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