API Lite Methods

From 1.1.0, Oz API Lite works with base64 as an input format and is also able to return the biometric templates in this format. To enable this option, add Content-Transfer-Encoding = base64 to the request headers.

version – component version check

Use this method to check what versions of components are used (available from 1.1.1).

Call GET /version

Input parameters

-

Request example

GET localhost/version

Successful response

In case of success, the method returns a message with the following parameters.

HTTP response content type: “application/json”.

Output parameters

Parameter name	Type	Description
core	String	API Lite core version number.
tfss	String	TFSS version number.
models	[String]	An array of model versions, each record contains model name and model version number.

Response example

200 OK
Content-Type: application/json
{
2	"core": "core_version",
3	"tfss": "tfss_version",
4	"models": [
5		{
6			"name": "model_name",
7			"version": "model_version"
8		}
9	]
10}

Biometry

health – biometric processor status check

Use this method to check whether the biometric processor is ready to work.

Call GET /v1/face/pattern/health

Input parameters

-

Request example

GET localhost/v1/face/pattern/health

Successful response

In case of success, the method returns a message with the following parameters.

HTTP response content type: “application/json”.

Output parameters

Parameter name	Type	Description
status	Int	0 – the biometric processor is working correctly. 3 – the biometric processor is inoperative.
message	String	Message.

Response example

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

extract – the biometric template extraction

The method is designed to extract a biometric template from an image.

HTTP request content type: “image / jpeg” or “image / png”

Call POST /v1/face/pattern/extract

Input parameters

Parameter name	Type	Description
Not specified*	Stream	Required parameter. Image to extract the biometric template. The “Content-Type” header field must indicate the content type.

*

The name itself is not mandatory for a parameter of the Stream type.

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/pattern/extract
Content-Type: image/jpeg
{Image byte stream}

Successful response

In case of success, the method returns a biometric template.

The content type of the HTTP response is “application/octet-stream”.

If you've passed Content-Transfer-Encoding = base64 in headers, the template will be in base64 as well.

Output parameters

Parameter name	Type	Description
Not specified*	Stream	A biometric template derived from an image

*

The name itself is not mandatory for a parameter of the Stream type.

Response example

200 OK
Content-Type: application/octet-stream
{Biometric template byte stream}

compare – the comparison of biometric templates

The method is designed to compare two biometric templates.

The content type of the HTTP request is “multipart / form-data”.

CallPOST /v1/face/pattern/compare

Input parameters

Parameter name	Type	Description
bio_feature	Stream	Required parameter. First biometric template.
bio_template	Stream	Required parameter. Second biometric template.

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/pattern/compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Message body length
--BOUNDARY--
Content-Disposition: form-data; name=”bio_feature”
Content_type: application/octet-stream
{Biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Biometric template byte stream}
--BOUNDARY--

Successful response

In case of success, the method returns the result of comparing the two templates.

HTTP response content type: “application/json”.

Output parameters

Parameter name	Type	Description
score	Float	The result of comparing two templates
decision	String	Recommended solution based on the score. approved – positive. The faces match. operator_required – additional operator verification is required. declined – negative result. The faces don't match.

Response example

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

verify – the biometric verification

The method combines the two methods from above, extract and compare. It extracts a template from an image and compares the resulting biometric template with another biometric template that is also passed in the request.

The content type of the HTTP request is “multipart / form-data”.

Call POST /v1/face/pattern/verify

Input parameters

Parameter name	Type	Description
sample	Stream	Required parameter. Image to extract the biometric template.
bio_template	Stream	Required parameter. The biometric template to compare with.

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/pattern/verify
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Message body length
--BOUNDARY--
Content-Disposition: form-data; name=”bio_template”
Content_type: application/octet-stream
{Biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”sample”
Content_type: image/jpeg
{Image byte stream}
--BOUNDARY--

Successful response

In case of success, the method returns the result of comparing two biometric templates and the biometric template.

The content type of the HTTP response is “multipart/form-data”.

Output parameters

Parameter name	Type	Description
score	Float	The result of comparing two templates
bio_feature	Stream	Biometric template derived from image

Response example

200 OK
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Message body length
--BOUNDARY--
Content-Disposition: form-data; name=”score”
Content_type: application/json
{“score”: 1.0}
--BOUNDARY--
Content-Disposition: form-data; name=”bio_feature”
Content_type: application/octet-stream
{Biometric template byte stream}
--BOUNDARY--

extract_and_compare – extracting and comparison of templates derived from two images

The method also combines the two methods from above, extract and compare. It extracts templates from two images, compares the received biometric templates, and transmits the comparison result as a response.

The content type of the HTTP request is “multipart / form-data”.

Call POST /v1/face/pattern/extract_and_compare

Input parameters

Parameter name	Type	Description
sample_1	Stream	Required parameter. First image.
sample_2	Stream	Required parameter. Second image

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/pattern/extract_and_compare
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: Message body length
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{Image byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”sample_2”
Content_type: image/jpeg
{Image byte stream}
--BOUNDARY--

Successful response

In case of success, the method returns the result of comparing the two extracted biometric templates.

HTTP response content type: “application / json”.

Output parameters

Parameter name	Type	Description
score	Float	The result of comparing the two extracted templates.
decision	String	Recommended solution based on the score. approved – positive. The faces are match. operator_required – additional operator verification is required. declined – negative result. The faces don't match.

Response example

200 OK
Content-Type: application/json
{“score”: 1.0, “decision”: “approved”}

compare_n – 1:N biometric template comparison

Use this method to compare one biometric template to N others.

The content type of the HTTP request is “multipart/form-data”.

Call POST /v1/face/pattern/compare_n

Input parameters

Parameter name	Type	Description
template_1	Stream	This parameter is mandatory. The first (main) biometric template
templates_n	Stream	A list of N biometric templates. Each of them should be passed separately but the parameter name should be templates_n. You also need to pass the filename in the header.

Request example

POST localhost/v1/face/pattern/compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: message body length
--BOUNDARY--
Content-Disposition: form-data; name=”template_1”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--

Successful response

In case of success, the method returns the result of the 1:N comparison.

HTTP response content type: “application / json”.

Output parameters

Parameter name	Type	Description
results	List[JSON]	A list of N comparison results. The Nth result contains the comparison result for the main and Nth templates. The result has the fields as follows:
*filename	String	A filename for the Nth template.
*score	Float	The result of comparing the main and Nth templates.
*decision	String	Recommended solution based on the score. approved – positive. The faces are match. operator_required – additional operator verification is required. declined – negative result. The faces don't match.

Response example

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

verify_n – 1:N biometric verification

The method combines the extract and compare_n methods. It extracts a biometric template from an image and compares it to N other biometric templates that are passed in the request as a list.

The content type of the HTTP request is “multipart/form-data”.

Call POST /v1/face/pattern/verify_n

Input parameters

Parameter name	Type	Description
sample_1	Stream	This parameter is mandatory. The main image.
templates_n	Stream	A list of N biometric templates. Each of them should be passed separately but the parameter name should be templates_n. You also need to pass the filename in the header.

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/pattern/verify_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: message body length
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{image byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”1.template”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”2.template”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”templates_n”; filename=”3.template”
Content_type: application/octet-stream
{biometric template byte stream}
--BOUNDARY--

Successful response

In case of success, the method returns the result of the 1:N comparison.

HTTP response content type: “application / json”.

Output parameters

Parameter name	Type	Description
results	List[JSON]	A list of N comparison results. The Nth result contains the comparison result for the template derived from the main image and the Nth template. The result has the fields as follows:
*filename	String	A filename for the Nth template.
*score	Float	The result of comparing the template derived from the main image and the Nth template.
*decision	String	Recommended solution based on the score. approved – positive. The faces are match. operator_required – additional operator verification is required. declined – negative result. The faces don't match.

Response example

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.template', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.template', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.template', 'score': 0.21, 'decision': 'declined'}
]}

extract_and_compare_n – 1:N template extraction and comparison

This method also combines the extract and compare_n methods but in another way. It extracts biometric templates from the main image and a list of other images and then compares them in the 1:N mode.

The content type of the HTTP request is “multipart/form-data”.

Call POST /v1/face/pattern/extract_and_compare_n

Input parameters

Parameter name	Type	Description
sample_1	Stream	This parameter is mandatory. The first (main) image.
samples_n	Stream	A list of N images. Each of them should be passed separately but the parameter name should be samples_n. You also need to pass the filename in the header.

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/pattern/extract_and_compare_n
Content-Type: multipart/form-data;
boundary=--BOUNDARY--
Content-Length: message body length
--BOUNDARY--
Content-Disposition: form-data; name=”sample_1”
Content_type: image/jpeg
{image byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”1.jpeg”
Content_type: image/jpeg
{image byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”2.jpeg”
Content_type: image/jpeg
{image byte stream}
--BOUNDARY--
Content-Disposition: form-data; name=”samples_n”; filename=”3.jpeg”
Content_type: image/jpeg
{image byte stream}
--BOUNDARY--

Successful response

In case of success, the method returns the result of the 1:N comparison.

HTTP response content type: “application / json”.

Output parameters

Parameter name	Type	Description
results	List[JSON]	A list of N comparison results. The Nth result contains the comparison result for the main and Nth images. The result has the fields as follows:
*filename	String	A filename for the Nth image.
*score	Float	The result of comparing the main and Nth images.
*decision	String	Recommended solution based on the score. approved – positive. The faces are match. operator_required – additional operator verification is required. declined – negative result. The faces don't match.

Response example

200 OK
Content-Type: application/json
{'results': [
    {'filename': '1.jpeg', 'score': 0.0, 'decision': 'declined'}, 
    {'filename': '2.jpeg', 'score': 1.0, 'decision': 'approved'}, 
    {'filename': '3.jpeg', 'score': 0.21, 'decision': 'declined'}
]}

Method errors

HTTP response content type: “application / json”.

HTTP response codes	The value of the “code” parameter	Description
400	BPE-002001	Invalid Content-Type of HTTP request
400	BPE-002002	Invalid HTTP request method
400	BPE-002003	Failed to read the biometric sample*
400	BPE-002004	Failed to read the biometric template
400	BPE-002005	Invalid Content-Type of the multiparted HTTP request part
400	BPE-003001	Failed to retrieve the biometric template
400	BPE-003002	The biometric sample* is missing face
400	BPE-003003	More than one person is present on the biometric sample*
500	BPE-001001	Internal bioprocessor error
400	BPE-001002	TFSS error. Call the biometry health method.

*

A biometric sample is an input image.

Liveness

health – checking the status of liveness processor

Use this method to check whether the liveness processor is ready to work.

Call GET /v1/face/liveness/health

Input parameters

• None.

Request example

GET localhost/v1/face/liveness/health

Successful response

In case of success, the method returns a message with the following parameters.

HTTP response content type: “application/json”.

Output parameters

Parameter name	Type	Description
status	Int	0 – the liveness processor is working correctly. 3 – the liveness processor is inoperative.
message	String	Message.

Response example

200 OK
Content-Type: application/json
{“status”: 0, message: “”}

detect – presentation attack detection

The method is designed to detect presentation attacks on images.

HTTP request content type: “image/jpeg” or “image/png”

Call POST /v1/face/liveness/detect

Input parameters

Parameter name	Type	Description
Not specified*	Stream	Required parameter. Picture. The “Content-Type” header field must indicate the content type.

*

The name itself is not mandatory for a parameter of the Stream type.

To transfer data in base64, add Content-Transfer-Encoding = base64 to the request headers.

Request example

POST localhost/v1/face/liveness/detect
Content-Type: image/jpeg
{Image byte stream}

Successful response

In case of success, the method returns an estimate of the presence of a presentation attack in the image.

HTTP response content type: “application/json”.

Output parameters

Parameter name	Type	Description
score	Float	Evaluation of the presence of a presentation attack in the image on a scale from 0 (no signs of an attack) to 1 (maximum confidence in the presence of an attack).
passed	Boolean	Recommended solution based on the score. True – there is no presentation attack on the image. False – the image contains a presentation attack.

Response example

200 OK
Content-Type: application/json
{“score”: 0.0, “passed”: True}

Method errors

HTTP response content type: “application / json”.

HTTP response codes	The value of the “code” parameter	Description
400	LDE-002001	Invalid Content-Type of HTTP request
400	LDE-002002	Invalid HTTP request method
400	LDE-002004	Failed to extract the biometric sample*
400	LDE-002005	Invalid Content-Type of the multiparted HTTP request part
500	LDE-001001	Liveness detection processor internal error
400	LDE-001002	TFSS error. Call the Liveness health method.

*

A biometric sample is an input image.