Welcome to Face API, an offering within YooniK 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 a secure HTTPS channel.
The Face API was designed to bring face authentication to any application in a 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.
{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.
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 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.
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.
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.22% |
IJBC | Verification | 1 in 10000 | 2.2% |
MegaFace | Identification | 1 in 10000 | 0.8% |
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.
This dataset is acquired in controlled illumination and face pose with large age difference between pictures (not quantified by the study):
The graphic shows that for an FMR of 0.000001 (1 in 1000000), our algorithm has a 0.6% false non-match rate performance. This level of performance in practical terms means that for this level of strict security, only 6 out of 1000 people will not be able to use the system.
This dataset consists of matching pairs acquired with uncontrolled illumination and uncontrolled pose having subjects with more than 12 years difference between pictures.
The mugshot results shows that for an FMR of 0.000001 (1 in 1000000), our algorithm has less than 0.4% false non-match rate performance. This level of performance in practical terms means that for this level of strict security, less than 4 out of 1000 people will not be able to use the system.
Endpoint to perform the biometric processing. Provided an image in Base64 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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
{warning} Conflict 409 can be raised if enrolled or gallery id does not exist.
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
{warning} Conflict 409 is raised if gallery id does not exist.
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
{warning} The conflict 409 status is raised when a gallery with the provided id already exists.
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
404 | Not Found | Error response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
404 | Not Found | Error response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
{warning} If the gallery does not exists the Conflict 409 Status Code is returned.
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 schema in request body
{success} Success
Status | Meaning | Schema |
---|---|---|
204 | No Content | No schema |
{danger} Error responses
Status | Meaning | Schema |
---|---|---|
400 | Bad Request | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
404 | Not Found | Error response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
{warning} If the template id already exists the HTTP 409 Status Code is returned.
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 |
{danger} Error responses
Status | Meaning | Schema |
---|---|---|
400 | Bad Request | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
404 | Not Found | Error response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
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 | Error response |
401 | Unauthorized | Error response |
403 | Forbidden | Forbidden response |
404 | Not Found | Error response |
405 | Method Not Allowed | Error response |
409 | Conflict | Error response |
500 | Internal Server Error | Error response |
Request processing of an image in base64 and the biometric processings.
{
"image": "string",
"processings": ["detect", "analyze", "templify"],
"configuration": [configA, configB]
}
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"] |
configuration | array | False | None | Array of extensible configurations. |
Enumerable types
Property | Value | Description |
---|---|---|
processings | "detect" | Face detection |
processings | "analyze" | Face analysis |
processings | "templify" | Face templification |
Extensible configurations for biometric processing.
{
"name": "string",
"value": "string"
}
Properties
Property | Value | Description |
---|---|---|
name | string | Configuration name. |
value | string | Configuration value. |
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_version": "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_version | string | Template version. |
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. |
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. |
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
}
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. |
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. |
{
"status_code": 400,
"phrase": "string",
"message": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
status_code | integer | True | None | HTTP status code. |
phrase | string | True | None | HTTP status code phrase. |
message | string | True | None | Detailed error message. |
{
"message": "Missing Authentication Token"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
message | string | True | None | Detailed error message. |
Encrypted face biometric template.
{
"template": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
template | string | True | None | Face biometric template. |
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. |
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 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. |
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. |
List of ids in a given gallery.
["id", ...]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string | False | None | Enrolled id. |
Candidates from identification request.
[
{
"template_id":"string",
"score": 0.5
},...
]
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
template_id | string | True | None | Enrolled id. |
score | string | False | None | Result score from comparing the identification template to the enrolled candidate. |
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.