Biometric in Things API


Welcome to the Biometric In Things (BiT) API, an offering within YooniK Services

The BiT API is built as a RESTful API hosted with in a local server running on-premises. All requests and responses are encoded in JSON. The concept of Biometric In Things was designed to bring face authentication to the edge in developer friendly fashion by exposing complex biometric functionalities via a simple REST API that can be integrated virtually in any programming language, in any environment.

Use cases

{primary} Live face capture

Detection and capture of aligned faces using ICAO Token Face Images according to ISO/IEC 19794-5 standard.

{primary} Live face verification

Design to build user authentication/verification in edge devices using reference face images already collected.

Common use cases are face authentication based on a passport collected photo like in our VR-eKiosk project or by providing the picture obtained with the provided face capture endpoint.

{primary} Face images verification

When you need to validate if the two face images belong to the same person you can use this functionality.

For example, when integrating with a passport reader on a Kiosk, you can perform a face verification step between the chip image and the scan passport photo to check for data integrity and increase the security of your applications.

Installation guide.

To start using YooniK BiT, please visit our website and find the subscription that fits your needs. Afterwards, please follow the instruction below that fit best your scenario:

Binaries installation - Windows only

  • Download the binary files. Use the BiT Zip password available in your dashboard to extract the files. Launch the batch file.

  • Call the setup API endpoint to install everything automatically. You need to provide the x-api-key key from your subscription in the HTTP request header. This request may take some time depending on your internet connection.

Docker file - Linux only

  • Contact us to obtained your docker file and launch the docker container.

  • Call the setup API endpoint to install everything automatically. You need to provide the x-api-key key from your subscription in the HTTP request header. This request may take some time depending on your internet connection.

Image formats

All endpoints that receive images accept jpg/jpeg, png and bmp formats converted in base64 images.

The recommended resolution for optimal results is at least VGA (640×480 px). Smaller resolutions are accepted, but might not provide optimal results. Larger resolutions are also accepted, but won't improve the authentication process significantly and can result in considerable increase of the processing times.

Camera compatibility

The YooniK.BiT supports out of the box the following camera drivers/types:

  • Video4Linux
  • UVC cameras
  • IP cameras (RTSP)
  • Intel RealSense cameras.

To ask for additional camera support please contact us.

Camera configuration

Changing camera is as simply as change two lines of the configuration file. By default the config is compatible with UVC and Video4Linux.

  • Use UVC/Video4Linux camera
 {
 "CameraFactory": {
      "TYPE": "Generic",
      "URL": 0
    }
 }
  • Use IP/RTSP camera
{
   "CameraFactory": {
        "TYPE": "Generic",
        "URL": "<ADD YOUR ENDPOINT HERE>"
    }
}
  • Use Intel RealSense cameras
{
   "CameraFactory": {
        "TYPE": "RS2",
        "URL": 0
   }
}

Generic endpoints

Monitoring

Endpoint that returns current API availability and processing capabilities status. Check if the camera is currently connected and available for processing.

GET | {base_url}/bit/status

{success} Success

Status Meaning Schema
200 OK No schema

{danger} Error responses

Status Meaning Schema
401 Unauthorized N/A
500 Internal Server Error N/A
503 Service Unavailable Error message

{warning} This method activates the camera and disconnects it again. Calling this method too often can resolve in high stress to the device leading to failure. It should not be used before calling processing methods since it will stress the camera and increase processing times.

Setup

Endpoint that configures the Biometric In Things server. Only needs to be call once. Until the setup call does not return a suucess status code, the software will not be operational.

GET | {base_url}/bit/setup

{success} Success

Status Meaning Schema
200 OK No schema

{danger} Error responses

Status Meaning Schema
401 Unauthorized N/A
500 Internal Server Error N/A

{warning} This method might take sometime to return depending on your internet speed since it s checking-out the latest face authentication models.

Processing endpoints

Live face capture

Endpoint that provides biometric capture capabilities using live stream from the configured camera. This endpoint can be used to capture the face for future reference or verification.

POST | {base_url}/bit/capture

Accepts: Capture Request

{success} Success

Status Meaning Schema
200 OK Capture Response

{danger} Error responses

Status Meaning Schema
400 Bad Request N/A
401 Unauthorized N/A
500 Internal Server Error N/A

Live face verification

Endpoint that provides verification capabilities by comparing reference image with the live capture from camera. The request accepts a face picture that can be obtained from passport scanning or any other source, e.g. using the capture endpoint.

POST | {base_url}/bit/verify

Accepts: Verify Request

{success} Success

Status Meaning Schema
200 OK Verify Response

{danger} Error responses

Status Meaning Schema
400 Bad Request N/A
401 Unauthorized N/A
500 Internal Server Error N/A

Verification of two images

Endpoint that provides verification capabilities between two face images. The request accepts two pictures, obtained for instance from the passport page scanning and passport chip, and provides a similarity score between the two.

POST | {base_url}/bit/verify_images

Accepts: Verify Images Request

{success} Success

Status Meaning Schema
200 OK Verify Images Response

{danger} Error responses

Status Meaning Schema
400 Bad Request N/A
401 Unauthorized N/A
500 Internal Server Error N/A

Schemas

Error message

String with generic error messages.

 "Error message"

{warning} It is strongly advised to not take action based on the text messages, these are meant for logging purposes only. Any action should be implemented based on status codes.

Capture request

Configurations to the face acquisition process.

{
  "capture_time_out": 10,
  "anti_spoofing": true,
  "live_quality_analysis": false
}

Properties

Name Type Required Restrictions Description
capture_time_out int False None Capture time out in seconds. Default is 10 seconds.
anti_spoofing boolean False None Flag to active liveness analysis. Default is true.
live_quality_analysis boolean False None Flag to activate image quality analysis in the face region. Default is True.

Capture response

Face capture with image and capture status results.

{
  "image": "string",
  "capture_status": [
    "capture_successful"
  ]
}

Properties

Name Type Required Restrictions Description
image string False None JPG Base 64 string face crop according to ISO/ICAO 19794-5 Token.
capture_status array True None Array with one or more enumerable to describe the success or failure during the capture process

Enumerable types

Property Value Description
capture_status capture_successful Capture successful.
capture_status capture_timedout Timeout passed with a face capture.
capture_status camera_failed Camera failed to start.
capture_status live_face_detection_failed Face was not detected during capture.
capture_status live_face_quality_failed Face was detected but without enough quality.
capture_status liveness_detection_failed Live face was not detected.

Verify request

Live face verification process request.

{
  "reference_image":"string",
  "capture_time_out": 10,
  "matching_score_threshold": 0.4,
  "anti_spoofing": true,
  "live_quality_analysis": false,
  "reference_live_quality_analysis": false
}

Properties

Name Type Required Restrictions Description
reference_image string True BMP, PNG or JPG Base 64 string reference face image.
matching_score_threshold double False None Configurable face matching threshold. Default is 0.4.
capture_time_out int False None Capture time out in seconds. Default is 10 seconds.
anti_spoofing boolean False None Flag to active liveness analysis. Default is true.
live_quality_analysis boolean False None Flag to activate image quality analysis in the face region. Default is false.
reference_quality_analysis boolean False None Flag to activate image quality analysis for the reference face image. Default is false.

Verify response

Face verification results.

{
  "matching_score": 0.8,
  "verified_image": "string",
  "verify_status": [
    "matching_successful"
  ]
}

Properties

Name Type Required Restrictions Description
matching_score double False None Matching score between live and reference image.
verified_image string False JPG Base 64 string thumbnail of the live matched image.
verify_status array True None Array with one or more enumerable to describe the success or failure during the verify process.

Enumerable types

Property Value Description
verify_status matching_successful Matching successful.
verify_status matching_failed Matching failed.
verify_status capture_timedout Timeout reached for the face match.
verify_status camera_failed Camera failed to start.
verify_status live_face_detection_failed Face was not detected during capture.
verify_status live_face_quality_failed Face was detected but without enough quality.
verify_status liveness_detection_failed Live face was not detected.
verify_status reference_face_detection_failed Reference face not detected.
verify_status reference_face_quality_failed Reference face without enough quality.

Verify Images Request

Provides two face images for comparison.

{
  "reference_image":"string",
  "probe_image": "string",
  "matching_score_threshold": 0.4,
}

Properties

Name Type Required Restrictions Description
reference_image string True BMP, PNG or JPG Base 64 string reference face image.
probe_image string True BMP, PNG or JPG Base 64 string probe face image.
matching_score_threshold double False minimum:-1 Configurable face matching threshold. Default is 0.4.

Verify Images Response

Face images verification results.

{
  "matching_score": 0.8,
  "verify_images_status": [
    "capture_successful"
  ]
}

Properties

Name Type Required Restrictions Description
matching_score double False None Matching score between live and reference image.
verified_image string False None JPG base 64 string thumbnail of the live matched image.
verify_images_status array True None Verify images status based.

Enumerable types

Property Value Description
verify_images_status matching_successful Matching successful.
verify_images_status matching_failed Matching failed.
verify_images_status probe_face_detection_failed Face was not detected during capture.
verify_images_status reference_face_detection_failed Reference face not detected.

Samples & SDKs

Please check our github space for more information about our integration SDKs.
We are looking into expand our current SDK offers, if you want to contribute please contact us.