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
Copy 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
Copy 200 OK
Content-Type: application/json
{“status” : 0 , message : “”} 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
Copy POST localhost/v 1 /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
Copy 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
Copy POST localhost/v 1 /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
Copy 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
Copy POST localhost/v 1 /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
Copy 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
Copy POST localhost/v 1 /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
Copy 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
Copy POST localhost/v 1 /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
Copy 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
Copy POST localhost/v 1 /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
Copy 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
Copy POST localhost/v 1 /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
Copy 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
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
Copy 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.
Copy POST /v 1 /face/liveness/detect HTTP/ 1.1
Host: localhost
Content-Type: image/jpeg
Content-Length: [the size of the message body]
[Image byte stream]
Copy 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.
Copy POST /v 1 /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--
Copy {
"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.
Copy POST /v 1 /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--
Copy {
"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"
}
