Image

Sending a face photo is mandatory for using our facial recognition API. To ensure greater reliability of the analyses performed, it is necessary for the client to follow some rules when taking the photo:

• The photo must contain only one face;
• The entire face must be visible in the photo;
• The face must occupy at least 15% of the photo area;
• The face must be facing the camera and parallel to it;
• The face must have open eyes;
• The face must have a closed mouth;
• The face must have a neutral expression and no smiles;
• The face must not be covered by any type of accessory (hats, glasses or masks).

In addition, only .jpeg and .png images with a maximum size of 3MB will be accepted.

File submission

Request Body

{
    "image": "base64_image_code"
}

Response Body

{ 
    "image_key": "f4b5337a-7b50-406e-8c8e-7d0e77b5aa02",
    "file_size": 47407,
    "width_px": 0,
    "height_px": 0,
    "created_at": "2020-07-29T18:40:57Z"
}

In cases where it is necessary to send an image without immediately executing facial registration or validation routines, a JSON object containing the image Base64 must be sent. For this, a POST request must be sent to the endpoint:

https://api.caas.qitech.app/face_recognition/image

Once sent, the image will be submitted to quality tests and, if approved, a JSON containing the image access key will be returned. This key should be used to reference the photo during registration or facial validation.

Attention

Only the Base64 code corresponding to the image should be sent.

Image quality validation

Response Body: Invalid image case

{
    "title": "image_quality",
    "description": "This image was not approved in quality assessment. The face is too close to image edges.",
    "image_status": "not_center"
}

When making a POST to the image endpoint, if the image is not sufficient for validation, an HTTP Status Code 400 will be returned.

The value of the description field is the message that explains why the image is invalid.

In addition, we return an enumerator image_status so that the reason why the image is invalid can be mapped. Below we have the listing of possible image_status:

image_status	description
no_faces	No face identified.
multiple_faces	More than one face identified.
close_face	Face too close to camera.
distant_face	Face too far from camera.
not_centered	Face is not centered enough.
inclined_face	Face is inclined.
wearing_acessories	Person is using accessories that cover part of the face.
facial_expression	The person has an open mouth, is smiling or has closed eyes.
brightness_problem	The image does not have adequate lighting.
sharpness_problem	The image is not sharp enough.

Attention - There are other reasons why we will return 400 (All related to invalid data). Only returns with title "image_quality" are the result of image quality validation and therefore should be passed on to the user.

File recovery

Image recovery

    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"

At any time it is possible to recover the sent images. For this, simply send a properly authenticated GET request to the endpoint:

https://api.caas.qitech.app/face_recognition/image/{image_key}/file

Where image_key is the value returned during image submission.

Processed file recovery

Processed image recovery

    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/cropped_file" \
         -H "Authorization: EXAMPLE_API_KEY"

After associating an image with a registration or validation, that image will be processed and a new image containing only the face used in facial recognition routines will be generated.

This image is available to be recovered through a properly authenticated GET request to the endpoint:

https://api.caas.qitech.app/face_recognition/image/{image_key}/cropped_file

Where image_key is the value returned during base image submission.

File metadata recovery

Metadata recovery

    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: EXAMPLE_API_KEY"

After sending an image to the API, it is possible to recover the image metadata using the endpoint:

https://api.caas.qitech.app/face_recognition/image/{image_key}

Where image_key is the value returned during image submission.