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.