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.
Request example
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]
Successful response example
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.
Request example
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--
Successful response example
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.
Request example
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--
Successful response example
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"
}