Face API

Welcome to Face API, an offering within Youverse Services.

This API allows you to perform any face processing (detection, analysis, template extraction) as well as performing verification (image to image matching) or identification (1 to many matching). All requests and responses are encoded in JSON and use communicated through a secure HTTPS channel.

The Face API was designed to bring face authentication to any application in developer friendly fashion by exposing complex biometric functionalities via a simple REST API that can be integrated virtually in any programming language, in any environment.

Use cases

{primary} Face detection & analysis

Detect and count the number of faces. In addition, we provide a set of metrics describing each face, such as pose and liveness.

{primary} Face images verification

When you need to validate if two face images belong to the same person you can use this functionality.

For example, when integrating with a passport reader on a Kiosk, you can perform a face verification step between the chip image and the scan passport photo to check for data integrity and increase the security of your applications.

{primary} Face biometric template creation

In case you want to create a user base using their face, but you don't want to use images to comply with privacy-by-design at its best, you can convert the face of your user to a irreversible encrypted abstraction of the face image that you can reuse for authentication scenarios.

{primary} Face identification

We also enable the use of our state of the art algorithms in identification scenarios (1 against many matching). This process is managed by gallery management API.

Biometric Performance

Our face authentication algorithm is a NIST-certified technology based on proprietary research in state-of-the-art deep convolutional neural networks and proprietary loss function, being amongst the world's top-performing biometric algorithms.

The National Institute of Standards and Technology is a US government agency that evaluates advanced technologies for the benefit of the public market. The Facial Recognition Vendor Test (FRVT) is considered the most rigorous and challenging evaluation for facial recognition technology; clients often will not even consider a vendor unless NIST FRVT is certified. This evaluation measures the performance of an algorithm on different datasets of variable control and quality, such as Visa and Mugshots.

False Match Operating (FMR)

The False Match Operating measures the likelihood that the biometric security system will incorrectly accept an access attempt by an unauthorized user. A system’s FMR typically is stated as the ratio of the number of false matches divided by the number of unauthorized verification attempts.

False Non Matches Rate(FNMR)

The False Non Matches Rate measures the likelihood that the biometric security system will incorrectly reject an access attempt by an authorized user. A system’s FNMR typically is stated as the ratio of the number of false non-matches divided by the number of authorized verification attempts.

Public Benchmarks

The two most commonly used verification datasets are the Labeled Faces in the Wild and the IJB-C. Both present captured in an uncontrolled environment, being IJB-C considerably more challenging offering subjects with total pose variation and occlusion. The IJB-C dataset presents images with an unconstrained pose, expression, lighting, and exposure, containing regular people, not easily recognizable celebrities. The MegaFace challenge aims to evaluate the performance of face recognition algorithms with up to a million distractors, i.e., up to a million people who are not in the probe set.

The table below shows the results for the three public benchmarks following the FMR vs FNMR trade-off curves.

Data set	Purpose	False Match Operating Point	False Non Matches Rate
LFW	Verification	1 in 100000	0.33%
IJBC	Verification	1 in 10000	2.9%
MegaFace	Identification	1 in 10000	1.6%

Face endpoints

Process

Endpoint to perform the biometric processing. Provided an image in base 64 and a set of configurations, this will return the detected faces, with corresponding quality metrics and biometric template.

POST | {base_url}/face/process

Accepts: Process request

{success} Success

Status	Meaning	Schema
200	OK	Process response

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
500	Internal Server Error	N/A

Verify Templates

Endpoint that computes the similarity score between two biometric templates.

POST | {base_url}/face/verify

Accepts: Verify request

{success} Success

Status	Meaning	Schema
200	OK	Matching result

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
500	Internal Server Error	N/A

Verify Id

Endpoint to perform a one to one matching against a user enrolled in a gallery.

POST | {base_url}/face/verify_id

Accepts: Verify id request

{success} Success

Status	Meaning	Schema
200	OK	Matching Result

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
409	Conflict	N/A
500	Internal Server Error	N/A

{warning} Conflict 409 can be raised if enrolled or gallery id does not exist.

Identify

Endpoint to perform face one-to-many comparison using a biometric template against a specific gallery.

POST | {base_url}/face/identify

Accepts: Identify request

{success} Success

Status	Meaning	Schema
200	OK	Candidates
Status	Meaning	Schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
409	Conflict	N/A
500	Internal Server Error	N/A

{warning} Conflict 409 is raised gallery id does not exist.

Gallery management

Gallery Creation

Endpoint to create a gallery to store the templates and their corresponding ids.

POST | {base_url}/gallery/{gallery_id}

Accepts: gallery_id parameter in the endpoint url

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
404	Not Found	N/A
409	Conflict	N/A
500	Internal Server Error	N/A

{warning} The conflict 409 status is raised when a gallery with the provided id already exists.

List gallery ids

Endpoint to list all ids enrolled in the specified gallery.

GET | {base_url}/gallery/{gallery_id}

Accepts: gallery_id parameter in the endpoint url

{success} Success

Status	Meaning	Schema
200	OK	Enrolled ids

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
404	Not Found	N/A
500	Internal Server Error	N/A

Gallery deletion

Endpoint that deletes the specified gallery.

DELETE | {base_url}/gallery/{gallery_id}

Accepts: gallery_id parameter in the endpoint url

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
404	Not Found	N/A
409	Conflict	N/A
500	Internal Server Error	N/A

{warning} If the gallery does not exists the Conflict 409 Status Code is returned.

Add template to gallery

Endpoint to add a template with to a given gallery.

POST| {base_url}/gallery/{gallery_id}/{template_id}

Accepts: gallery_id and template_id in the endpoint URL and a Template Request schema in request body

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
404	Not Found	N/A
409	Conflict	N/A
500	Internal Server Error	N/A

{warning} If the template id already exists the HTTP 409 Status Code is returned.

Get template

Endpoint to return a template from a given gallery.

GET | {base_url}/gallery/{gallery_id}/{template_id}

Accepts: gallery_id and template_id in the endpoint URL.

{success} Success

Status	Meaning	Schema
200	OK	Template request

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
404	Not Found	N/A
500	Internal Server Error	N/A

Delete template from gallery

Endpoint to delete template from a given gallery.

DELETE | {base_url}/gallery/{gallery_id}/{template_id}

Accepts: gallery_id and template_id in the endpoint URL.

{success} Success

Status	Meaning	Schema
204	No Content	No schema

{danger} Error responses

Status	Meaning	Schema
400	Bad Request	N/A
401	Unauthorized	N/A
404	Not Found	N/A
409	Conflict	N/A
500	Internal Server Error	N/A

Schemas

Process Request

Request processing of an image in base64 and the biometric processings.

{
    "image": "string",
    "processings": ["detect", "analyze"]
}

Properties

Name	Type	Required	Restrictions	Description
image	string	True	BMP, PNG or JPG	Base 64 image
processings	array	False	None	Array of processings. Default is ["detect, "analyze", "templify"]

Enumerable types

Property	Value	Description
processings	"detect"	Face detection
processings	"analyze"	Face analysis
processings	"templify"	Face templification

Process Response

Processed image results. Each element of the array corresponds to a different face detected.

[
{
    "biometric_type": "face",
    "x": 0.0,
    "y": 0.0,
    "z": 0.0,
    "width": 0.0,
    "height": 0.0,
    "matching_score": 0.0,
    "matching_image": "string",
    "template": "string",
    "template_id": "string",
    "tracking_id": "string",
    "biometric_points": [firstPoint, secondPoint,...],
    "quality_metrics": [firstMetric, secondMetric...]    
}
]

Properties

Property	Value	Description
biometric_type	string	Always returns "face".
x	double	Face center coordinate x.
y	double	Face center coordinate y.
z	double	Face center coordinate y.
width	double	Face bounding box width.
height	double	Face bounding box height.
matching_score	double	Matching score obtained with template_id person.
matching_image	string	Thumbnail/crop used for template extraction.
template	string	Biometric template.
template_id	string	Template id.
tracking_id	string	N/A from the API consumption perspective.
biometric_points	array	Array of face biometric points.
quality_metrics	array	Array of face quality metrics.

Biometric point

Representation of face biometric point.

{
    "name": "point name",
    "x": 0,
    "y": 0
}

Properties

Property	Value	Description
x	integer	Point y coordinate.
y	integer	Point y coordinate.
name	string	Point coordinate name.

Enumerable Types

Property	Value	Description
name	right_eye	Right eye center.
name	left_eye	Left eye center.
name	nose_tip	Nose tip point.
name	mouth_right	Mouth right corner point.
name	mouth_left	Mouth left corner point.
name	right_eye_right_corner	Right eye right corner point.
name	left_eye_left_corner	Left eye left corner point.
name	chin	Chin point.
name	undefined	Undefined point.

Quality metric

Representation of face quality metric, tresholds, and test decision.

{
    "name": "metric name",
    "value": 0.5,
    "enum": "string enumerable if applicable",
    "bottom_threshold": 0.0,
    "top_threshold": 1.0,
    "test": true
}

Properties

Property	Value	Description
name	string	Metric name.
value	double	Metric value.
enum	string	String with metric value for enumerables.
bottom_threshold	double	Bottom threshold.
top_threshold	double	Top threshold.
test	boolean	Metric test according to threshold.

Enumerable Types

Property	Value	Description
name	brightness	Average face brightness.
name	light_uniformity	Light distribution measurement.
name	contrast	Face contrast measurement.
name	sharpness	Face sharpness measurement.
name	roll	Face roll angle.
name	pitch	Face pitch angle.
name	yaw	Face yaw angle.
name	liveness	Face liveness measurement.
name	mask_present	Face mask presence detection.
name	age	Not yet available.
name	gender	Not yet available.
name	emotion	Not yet available.
name	pose_frontalness	Frontal pose measurement .
name	background_uniformity	Not yet available.
name	ethnicity	Undefined point.
name	confidence	Face detection confidence.
name	grayscale_density	Measurement of number of levels of gray.
name	relative_horizontal_size	Face width per image width.
name	relative_vertical_size	Face height per image height.
name	relative_interocular_distance	Interocular distance per image width.
name	relative_horizontal_deviation	Relative deviation from image center.
name	relative_vertical_deviation	Relative deviation from image center.
name	global_quality	Single valued global image quality metric.

Template request

Encrypted face biometric template.

{
    "template": "string"
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Face biometric template.

Matching result

Match result between two faces biometric templates or two face images.

{
    "score": 0.0
}

Properties

Name	Type	Required	Restrictions	Description
score	double	True	None	Similarity between two biometric templates.

Verify Request

Verification of two face biometric templates.

{
    "first_template": "string",
    "second_template": "string"
}

Properties

Name	Type	Required	Restrictions	Description
first_template	string	True	None	Encrypted face biometric template.
second_template	string	True	None	Encrypted face biometric template.

Verify id request

Verify id from a given gallery

{
    "template": "string",
    "template_id": "string",
    "gallery_id": "string"
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Encrypted face biometric template.
template_id	string	True	None	Corresponds to the enrolled id gallery.
gallery_id	string	False	None	Gallery id.

Identify request

Identification of template in a given gallery.

{
    "template": "string",
    "candidate_list_length": 1,
    "minimum_score": -1,
    "gallery_id": "string"
}

Properties

Name	Type	Required	Restrictions	Description
template	string	True	None	Encrypted face biometric template.
candidate_list_length	integer	False	minimum: 1	Maximal number of candidates to be returned.
minimum_score	string	False	minimum: -1	Minimum value for a positive match.
gallery_id	string	False	None	Gallery id.

Enrolled ids

List of ids in a given gallery.

["id", ...]

Properties

Name	Type	Required	Restrictions	Description
id	string	False	None	Enrolled id.

Candidates

Candidates from identification request.

[
    {
        "template_id":"string",
        "score": 0.5
    },...
]

Properties

Name	Type	Required	Restrictions	Description
template_id	string	False	None	Enrolled id.
score	string	False	None	Result score from comparing the identification template to the enrolled candidate.

Samples & SDKs

Please check our github space for more information about our integration SDKs.
We are looking into expand our current SDK offers, if you want to contribute please contact us.

Get started

Products

IAM Integrations

Face API

Use cases

Biometric Performance

False Match Operating (FMR)

False Non Matches Rate(FNMR)

Public Benchmarks

Face endpoints

Process

Verify Templates

Verify Id

Identify

Gallery management

Gallery Creation

List gallery ids

Gallery deletion

Add template to gallery

Get template

Delete template from gallery

Schemas

Process Request

Process Response

Biometric point

Quality metric

Properties

Enumerable Types

Template request

Matching result

Verify Request

Verify id request

Identify request

Enrolled ids

Candidates

Samples & SDKs