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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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”.

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

Response example

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

detect – presentation attack detection

The detect method is made to reveal presentation attacks. It detects a face in each image or video (since 1.2.0), sends them for analysis, and returns a result.

The method supports the following content types:

image/jpeg or image/png for an image;
multipart/form-data for images, videos, and archives. You can use payload to add any parameters that affect the analysis.

To run the method, call POST /{version}/face/liveness/detect.

Image

Accepts an image in JPEG or PNG format. No payload attached.

Request example

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Type: image/jpeg
Content-Length: [the size of the message body]
[Image byte stream]

Successful response example

HTTP/1.1 200 OK
Content-Type: application/json
{
  "passed": false,
  "score": 0.999484062
}

Multipart/form-data

Accepts the multipart/form-data request.

Each media file should have a unique name, e.g., media_key1, media_key2.
The payload parameters should be a JSON placed in the payload field.

Temporary IDs will be deleted once you get the result.

Request example

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Length: [the size of the message body]
Content-Type: multipart/form-data; boundary=--BOUNDARY--

--BOUNDARY--
Content-Disposition: form-data; name="media_key1"; filename="video.mp4"
Content-Type: multipart/form-data; 

[media file byte stream]
--BOUNDARY--
Content-Disposition: form-data; name="payload"

    {
        "folder:meta_data": {
            "partner_side_folder_id": "partner_side_folder_id_if_needed",
            "person_info": {
                "first_name": "John",
                "middle_name": "Jameson",
                "last_name": "Doe"
            }
        },
        "resolution_endpoint": "https://www.your-custom-endpoint.com",
        "media:meta_data": {
            "media_key1": {
                "foo": "bar2"
            }
        },
        "media:tags": {
            "media_key1": [
                "video_selfie",
                "video_selfie_blank"
            ]
        },
        "analyses": [
          {
            "type": "quality",
            "meta_data": {
              "example1": "some_example1"
            },
            "params": {
                "threshold_spoofing": 0.6,
                "extract_best_shot": false
            }
          }
]
    }
--BOUNDARY--

Successful response example

{
    "company_id": null,
    "time_created": 1720180784.769608,
    "folder_id": "folder_id", // temporary ID
    "user_id": null,
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "resolution_status": "FINISHED",
    "resolution_comment": "[]",
    "system_resolution": "SUCCESS",
    "resolution_time": null,
    "resolution_author_id": null,
    "resolution_state_hash": null,
    "operator_comment": null,
    "operator_status": null,
    "is_cleared": null,
    "meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
    "technical_meta_data": {},
    "time_updated": 1720180787.531983,
    "media": [
        {
            "folder_id": "folder_id", // temporary ID
            "media_id": "video_id", // temporary ID
            "media_type": "VIDEO_FOLDER",
            "info": {
                "thumb": null,
                "video": {
                    "duration": 3.76,
                    "FPS": 22.83,
                    "width": 960,
                    "height": 720,
                    "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                    "size": 6017119,
                    "mime-type": "video/mp4"
                }
            },
            "tags": [
                "video_selfie",
                "video_selfie_blank",
                "orientation_portrait"
            ],
            "original_name": "video-5mb.mp4",
            "original_url": null,
            "company_id": null,
            "technical_meta_data": {},
            "time_created": 1719573752.78253,
            "time_updated": 1720180787.531801,
            "meta_data": {
                "foo4": "bar5"
            },
            "thumb_url": null,
            "folder_time_created": null,
            "video_id": "video_id", // temporary ID
            "video_url": null
        }
    ],
    "analyses": [
        {
            "analyse_id": null,
            "analysis_id": null,
            "folder_id": "folder_id", // temporary ID
            "folder_time_created": null,
            "type": "QUALITY",
            "state": "FINISHED",
            "company_id": null,
            "group_id": null,
            "results_data": null,
            "confs": {
                "threshold_replay": 0.5,
                "extract_best_shot": false,
                "threshold_liveness": 0.5,
                "threshold_spoofing": 0.42
            },
            "error_message": null,
            "error_code": null,
            "resolution_operator": null,
            "technical_meta_data": {},
            "time_created": 1720180784.769944,
            "time_updated": 1720180787.531877,
            "meta_data": {
                "some_key": "some_value"
            },
            "source_media": [
                {
                    "folder_id": "folder_id", // temporary ID
                    "media_id": "video_id", // temporary ID
                    "media_type": "VIDEO_FOLDER",
                    "info": {
                        "thumb": null,
                        "video": {
                            "duration": 3.76,
                            "FPS": 22.83,
                            "width": 960,
                            "height": 720,
                            "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                            "size": 6017119,
                            "mime-type": "video/mp4"
                        }
                    },
                    "tags": [
                        "video_selfie",
                        "video_selfie_blank",
                        "orientation_portrait"
                    ],
                    "original_name": "video-5mb.mp4",
                    "original_url": null,
                    "company_id": null,
                    "technical_meta_data": {},
                    "time_created": 1719573752.78253,
                    "time_updated": 1720180787.531801,
                    "meta_data": {
                        "foo4": "bar5"
                    },
                    "thumb_url": null,
                    "folder_time_created": null,
                    "video_id": "video_id", // temporary ID
                    "video_url": null
                }
            ],
            "results_media": [
                {
                    "company_id": null,
                    "media_association_id": "video_id", // temporary ID
                    "analysis_id": null,
                    "results_data": {
                        "confidence_spoofing": 0.000541269779
                    },
                    "source_media_id": "video_id", // temporary ID
                    "output_images": [],
                    "collection_persons": [],
                    "folder_time_created": null
                }
            ],
            "resolution_status": "SUCCESS",
            "resolution": "SUCCESS"
        }
    ]
}

Multipart/form-data with Best Shot

To extract the best shot from your video or archive, in analyses, set extract_best_shot = true (as shown in the request example below). In this case, API Lite will analyze your archives and videos, and, in response, will return the best shot. It will be a base64 image in analysis->output_images->image_b64.

Additionally, you can change the Liveness threshold. In analyses, set the new threshold in the threshold_spoofing parameter. If the resulting score will be higher than this parameter's value, the analysis will end up with the DECLINED status. Otherwise, the status will be SUCCESS.

Request example

POST /v1/face/liveness/detect HTTP/1.1
Host: localhost
Content-Length: [the size of the message body]
Content-Type: multipart/form-data; boundary=--BOUNDARY--

--BOUNDARY--
Content-Disposition: form-data; name="media_key1"; filename="video.mp4"
Content-Type: multipart/form-data; 

[media file byte stream]
--BOUNDARY--
Content-Disposition: form-data; name="payload"

    {
        "folder:meta_data": {
            "partner_side_folder_id": "partner_side_folder_id_if_needed",
            "person_info": {
                "first_name": "John",
                "middle_name": "Jameson",
                "last_name": "Doe"
            }
        },
        "resolution_endpoint": "https://www.your-custom-endpoint.com",
        "media:meta_data": {
            "media_key1": {
                "foo": "bar2"
            }
        },
        "media:tags": {
            "media_key1": [
                "video_selfie",
                "video_selfie_blank"
            ]
        },
        "analyses": [
          {
            "type": "quality",
            "meta_data": {
              "example1": "some_example1"
            },
            "params": {
                "threshold_spoofing": 0.6,
                "extract_best_shot": true
            }
          }
]
    }
--BOUNDARY--

Successful response example

{
    "company_id": null,
    "time_created": 1720177371.120899,
    "folder_id": "folder_id", // temporary ID
    "user_id": null,
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "resolution_status": "FINISHED",
    "resolution_comment": "[]",
    "system_resolution": "SUCCESS",
    "resolution_time": null,
    "resolution_author_id": null,
    "resolution_state_hash": null,
    "operator_comment": null,
    "operator_status": null,
    "is_cleared": null,
    "meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }
    },
    "technical_meta_data": {},
    "time_updated": 1720177375.531137,
    "media": [
        {
            "folder_id": "folder_id", // temporary ID
            "media_id": "media_id", // temporary ID
            "media_type": "VIDEO_FOLDER",
            "info": {
                "thumb": null,
                "video": {
                    "duration": 3.76,
                    "FPS": 22.83,
                    "width": 960,
                    "height": 720,
                    "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                    "size": 6017119,
                    "mime-type": "video/mp4"
                }
            },
            "tags": [
                "video_selfie",
                "video_selfie_blank",
                "orientation_portrait"
            ],
            "original_name": "video-5mb.mp4",
            "original_url": null,
            "company_id": null,
            "technical_meta_data": {},
            "time_created": 1719573752.781861,
            "time_updated": 1720177373.772401,
            "meta_data": {
                "foo4": "bar5"
            },
            "thumb_url": null,
            "folder_time_created": null,
            "video_id": "media_id", // temporary ID
            "video_url": null
        }
    ],
    "analyses": [
        {
            "analyse_id": null,
            "analysis_id": null,
            "folder_id": "folder_id", // temporary ID
            "folder_time_created": null,
            "type": "QUALITY",
            "state": "FINISHED",
            "company_id": null,
            "group_id": null,
            "results_data": null,
            "confs": {
                "threshold_replay": 0.5,
                "extract_best_shot": true,
                "threshold_liveness": 0.5,
                "threshold_spoofing": 0.42
            },
            "error_message": null,
            "error_code": null,
            "resolution_operator": null,
            "technical_meta_data": {},
            "time_created": 1720177371.121241,
            "time_updated": 1720177375.531043,
            "meta_data": {
                "some_key": "some_value"
            },
            "source_media": [
                {
                    "folder_id": "folder_id", // temporary ID
                    "media_id": "media_id", // temporary ID
                    "media_type": "VIDEO_FOLDER",
                    "info": {
                        "thumb": null,
                        "video": {
                            "duration": 3.76,
                            "FPS": 22.83,
                            "width": 960,
                            "height": 720,
                            "md5": "8879b4fa9ee7add77aceb8d7d5d7b92d",
                            "size": 6017119,
                            "mime-type": "video/mp4"
                        }
                    },
                    "tags": [
                        "video_selfie",
                        "video_selfie_blank",
                        "orientation_portrait"
                    ],
                    "original_name": "video-5mb.mp4",
                    "original_url": null,
                    "company_id": null,
                    "technical_meta_data": {},
                    "time_created": 1719573752.781861,
                    "time_updated": 1720177373.772401,
                    "meta_data": {
                        "foo4": "bar5"
                    },
                    "thumb_url": null,
                    "folder_time_created": null,
                    "video_id": "media_id", // temporary ID
                    "video_url": null
                }
            ],
            "results_media": [
                {
                    "company_id": null,
                    "media_association_id": "media_id", // temporary ID
                    "analysis_id": null,
                    "results_data": {
                        "confidence_spoofing": 0.000541269779
                    },
                    "source_media_id": "media_id", // temporary ID
                    "output_images": [
                        {
                            "folder_id": "folder_id", // temporary ID
                            "media_id": "media_id", // temporary ID
                            "media_type": "IMAGE_RESULT_ANALYSIS_SINGLE",
                            "info": {
                                "thumb": null,
                                "original": {
                                    "md5": "e6effeceb94e79b8cb204c6652283b57",
                                    "width": 720,
                                    "height": 960,
                                    "size": 145178,
                                    "mime-type": "image/jpeg"
                                }
                            },
                            "tags": [],
                            "original_name": "<PIL.JpegImagePlugin.JpegImageFile image mode=RGB size=720x960 at 0x766811DF8E90>",
                            "original_url": null,
                            "company_id": null,
                            "technical_meta_data": {},
                            "time_created": 1719573752.781861,
                            "time_updated": 1719573752.781871,
                            "meta_data": null,
                            "folder_time_created": null,
                            "image_b64": "",
                            "media_association_id": "media_id" // temporary ID
                        }
                    ],
                    "collection_persons": [],
                    "folder_time_created": null
                }
            ],
            "resolution_status": "SUCCESS",
            "resolution": "SUCCESS"
        }
    ]
}

The payload field

{
    "folder:meta_data": {
        "partner_side_folder_id": "partner_side_folder_id_if_needed",
        "person_info": {
            "first_name": "John",
            "middle_name": "Jameson",
            "last_name": "Doe"
        }   },
    "resolution_endpoint": "https://www.your-custom-endpoint.com",
    "media:meta_data": {
        "media_key1": {
            "foo": "bar2",
            "additional_info": "additional_info" // might affect the score
        },
        "media_key2": {
            "foo2": "bar3"
        },
        "media_key3": {
            "foo4": "bar5"
        }
    },
    "media:tags": {
        "media_key1": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ],
        "media_key2": [
            "photo_selfie"
        ],
        "media_key3": [
            "video_selfie",
            "video_selfie_blank",
            "orientation_portrait"
        ]
    },
"analyses": [
    {
      "type": "quality",
      "meta_data": {
        "some_key": "some_value"
      },
      "params": {
      	"threshold_spoofing": 0.42, // affects resolution
      	"extract_best_shot":true // analysis will return the best shot
      }
    }
  ]
}

Method errors

HTTP response content type: “application / json”.

A biometric sample is an input image.