LogoLogo
To the Oz WebsiteOz API ReferenceContact Us
  • General
    • Oz Liveness and Biometry Key Concepts
      • Solution Architecture
      • Liveness, Face Matching, Black List Checks
      • Passive and Active Liveness
      • Hybrid Liveness
      • Oz API Key Concepts
      • Oz API vs. Oz API Lite
      • SaaS, On-premise, On-device: What to Choose
      • Oz Licensing Options
    • Integration Quick Start Guides
      • Server-Based Liveness
        • How to Integrate Server-Based Liveness into Your Web Application
        • How to Integrate Server-Based Liveness into Your Mobile Application
        • How to Check Your Media for Liveness without Oz Front End
      • On-Device Liveness
        • How to Integrate On-Device Liveness into Your Mobile Application
      • Face Matching
        • How to Add Face Matching of Liveness Video with a Reference Photo From Your Database
        • How to Add Photo ID Capture and Face Matching to Your Web or Mobile Application
  • Guides
    • Developer Guide
      • API
        • Oz API
          • Working with Oz System: Basic Scenarios
            • Authentication
            • Uploading Media
            • Liveness
            • Biometry (Face Matching)
            • Best Shot
            • Blacklist Check
              • Blacklist (Collection) Management in Oz API
            • Quantitative Results
            • Using a Webhook to Get Results
            • Single Request
            • Instant API: Non-Persistent Mode
          • System Objects
          • User Roles
          • Types of Analyses and What They Check
          • Rules of Assigning Analyses
          • Statuses in API
          • Media Tags
          • Metadata
          • API Error Codes
          • Oz API Postman Collections
          • Changelog
        • Oz API Lite
          • API Lite Methods
          • Oz API Lite Postman Collection
          • Changelog
      • SDK
        • Oz Mobile SDK (iOS, Android, Flutter)
          • On-Device Mode
          • Android
            • Getting a License for Android SDK
              • Master License for Android
            • Adding SDK to a Project
            • Connecting SDK to API
            • Capturing Videos
            • Checking Liveness and Face Biometry
            • Customizing Android SDK
              • How to Restore the Previous Design after an Update
            • Android Localization: Adding a Custom or Updating an Existing Language Pack
            • Android SDK Methods and Properties
            • Changelog
          • iOS
            • Getting a License for iOS SDK
              • Master License for iOS
            • Adding SDK to a Client’s Mobile App
            • Connecting SDK to API
            • Capturing Videos
            • Checking Liveness and Face Biometry
            • Customizing iOS SDK Interface
              • How to Restore the Previous Design after an Update
            • iOS Localization: Adding a Custom or Updating an Existing Language Pack
            • iOS SDK Methods and Properties
            • Changelog
          • Flutter
            • How to Install and Use Oz Flutter Plugin
            • Flutter SDK Methods and Properties
            • Changelog
        • Oz Liveness Web SDK
          • Web Plugin
            • Adding the Plugin to Your Web Page
            • Launching the Plugin
              • Description of the on_complete Callback
              • Description of the on_result Callback
              • Capturing Video and Description of the on_capture_complete Callback
              • Description of the on_error Callback
            • Closing or Hiding the Plugin
            • Localization: Adding a Custom Language Pack
            • Look-and-Feel Customization
              • Customization Options for Older Versions (before 1.0.1)
            • Security Recommendations
            • Browser Compatibility
            • No-Server Licensing
          • Changelog
    • Administrator Guide
      • Deployment Architecture
      • Installation in Docker
      • Installation in Kubernetes
      • Performance and Scalability Guide
      • Publishing API Methods in the Internet: Security Recommendations
      • Monitoring
      • License Server
      • Web Adapter Configuration
        • Installation and Licensing
        • Configuration File Settings
        • Configuration Using Environment Variables
        • Server Configuration via Environment Variables
      • Oz API Configuration
    • User Guide
      • Oz Web UI
        • Requesting Analyses
        • Users and Companies
        • Blacklist
        • Statistics
        • Settings
        • Changelog
  • Other
    • Media Quality Requirements
    • Oz SDK Media Quality Checks
    • Media File Size Overview
    • Compatibility
    • FAQ
    • Tips and Tricks
      • Oz Liveness Gestures: Table of Correspondence
      • Sudo without Password
      • Android: Certificate Validation Error
    • Previous Documentation
      • Mobile SDK
        • Android
          • Interactions with the Oz API Server
          • Uploading and Analyzing Media
        • iOS
          • Uploading and Analyzing Media
      • User Guides
        • Oz Demo Kit
        • Web UI
      • Oz Modules Installation
        • Standalone Installer
        • Oz System Lite
Powered by GitBook
On this page
  • version – component version check
  • Biometry
  • health – biometric processor status check
  • extract – the biometric template extraction
  • compare – the comparison of biometric templates
  • verify – the biometric verification
  • extract_and_compare – extracting and comparison of templates derived from two images
  • compare_n – 1:N biometric template comparison
  • verify_n – 1:N biometric verification
  • extract_and_compare_n – 1:N template extraction and comparison
  • Method errors
  • Liveness
  • health – checking the status of liveness processor
  • detect – presentation attack detection
  • Method errors

Was this helpful?

Export as PDF
  1. Guides
  2. Developer Guide
  3. API
  4. Oz API Lite

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

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.

PreviousOz API LiteNextOz API Lite Postman Collection

Last updated 2 months ago

Was this helpful?