VideoLiveDetection Web API (preview)

POST /videolivedetection


Performs a face liveness detection (see Face Liveness Detection) on the attached video.

This new API is in a preview state, i.e. we are still optimizing our parameters and, as with all our services, we are continuously improving the live detection neural networks.

The liveness detection on videos itself is a straightforward procedure: we start with the first frame of the video, try to detect a suitable face in this frame and perform a standard live detection on the facial image. We repeat the procedure for frames with some offset (~300 millisecond) in the video until a break condition is reached. A final decision is made on the number of live images vs fake images vs failed suitable face detections.

Please ensure that the uploaded video is not too big. A video of about three seconds length should be enough.

Request Information

Authentication

This API call requires Basic Authentication, i.e. you have to provide an HTTP authorization header using the authorization method Basic and the base64 encoded string App-ID:App-Secret. To receive the necessary BWS WebAPI access data (App-ID and App-Secret) you have to register your application on the BWS Portal first. This requires a valid BWS subscription.

Parameters

This API has no required parameters. An optional state parameter can be provided which is simply passed through to the BWS log and to the returned object.

The video is simply attached to the POST using a multipart/form-data body content.

Response

The video liveness detection API returns a LiveDetectionResult object, that primarily contains the flag Success, which indicates, whether the live detection succeeded or not:

SuccessBoolean flag indicating whether the video is recorded from a live person.
FailedToAcquireBoolean flag that, in case live detection failed, indicates, whether the BWS had problems finding suitable faces in the video.
JobIDA unique ID to identify this VideoLiveDetection job with the BWS log.
StateAn optional provided status string that is also added to the BWS log.


In case something goes wrong, an error HTTP status code is returned together with some additional information if available.

Response HTTP Status Codes

The call returns one of the standard HTTP status codes. With the success code (200) you receive the described LiveDetectionResult object in the body text. With erroneous codes you typically get a Message field within the body text describing the error. The most commonly returned codes are:

200 OKThe response body contains the LiveDetectionResult object.
400 Bad RequestNo or more than one streams have been submitted. The response body typically has a Message field containing the error code:
  • "OneVideoStreamExpected": Exactly one video stream is expected.
415 Unsupported Media TypeThe request-content is not a multipart MIME content.
401 UnauthorizedBasic Authentication is required.
500 Internal Server ErrorA server side exception occurred. The content may contain a Message and an ExceptionMessage.

Sample Code

private static async Task<bool> VideoLiveDetectionAsync(Stream videoStream)
{
	using (var client = new HttpClient())
	using (var streamContent = new StreamContent(videoStream))
	using (var content = new MultipartFormDataContent())
	{
		content.Add(streamContent);
		
		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", "...");

		using (var response = await httpClient.PostAsync("https://bws.bioid.com/extension/videolivedetection", content);
		{
			if (response.StatusCode == HttpStatusCode.OK)
			{
				string result = await response.Content.ReadAsStringAsync();
				Console.Write("Result: " + result);
				
				var json = JObject.Parse(result);
				bool success = (bool)json["Success"];
				bool fta = (bool)json["FailedToAcquire"];
				...
				
				return success;
			}

			Console.WriteLine(response.StatusCode.ToString());
			return false;
		}
	}   
}