Endpoints - ultima demanda de alteração - pedro 17/03/2022

# Face

# Detect

The Face Detect method allows you to process images in order to detect human faces. We highly recommend that you use this resource to evaluate the overall quality of the image.

Our face detection and recognition models do not consider faces that are not completely inside the given image input. For best results, consider using only non-ocluded faces.

Headers
Authorization REQUIRED / string (jwt token)

Body
image_file string (binary)
client_declaration_enduser_consent boolean (true/false)

POST https://api.getperse.com/v0/face/detect

$ curl \
 -X POST https://api.getperse.com/v0/face/detect \
 -H "Content-Type: multipart/form-data" \
 -H "Authorization: Bearer <JWT token>" \
 -F "[email protected]" \
 -F "client_declaration_enduser_consent=true"

Response

200
The Detect object

total_faces number
Total number of faces detected on a single image file.

faces array[object]
List of all faces by Perse model.
- landmarks object
  Object with coordinates (x,y) for each of face's landmarks.
- bounding_box number
  Array of coordinates that forms a bounding box around the face (top left corner, bottom right corner, width, height).
- face_metrics object
  An object with five properties indicating the overall picture quality of the detected face. Those metrics are related to the cropped area of the image that has a face, not the whole image file.
  - underexposure number (0-1)
    Indicates loss of shadow detail (closer to 0 is better).
  - overexposure number (0-1)
    Indicates loss of highlight detail (closer to 0 is better).
  - sharpness number (0-1)
    Indicates intensity of motion blur (closer to 1 is better).
  - color number (0-1)
    Indicates if there is a color degradation (closer to 0 is better).
  - rotation number (0-360)
    Indicates if the face is rotated .This metric uses the head orientation on the 3 axis (pitch,roll,yaw) and outputs the result score. This filter indicates if the person is looking straight to the camera. (closer to 0 is better)
- liveness_score number
  Indicates the confidence that a detected face is from a person or from a spoof attack (1 means higher confidence of being a person).
- default_thresholds object
  An object that contains default and recommended thresholds to verify image quality.
  - underexposure number
    Indicates the recommended threshold for underexposure. If the value is lower than the threshold, it means that the image is within the recommended limit for darkness.
  - overexposure number
    Indicates the recommended threshold for overexposure. If the value is lower than the threshold, it means that the image is within the recommended limit for brightness.
  - sharpness number
    Indicates the recommended threshold for sharpness. If the value is higher than the threshold, it means that the image is within the recommended limit for blur.
  - color number
    Indicates the recommended threshold for color. If the color value is lower than the color threshold, it means the image has no degradation in color.
  - rotation number
    Indicates the recommended threshold for rotation. If the rotation value is lower than the rotation threshold, it means the face is not rotated.
  - liveness number
    Indicates the recommended threshold for liveness. If the value is lower than the threshold, it means that the person on the image is probably not a real person. In order to have reliable results for liveness, the other quality parameters should be within their recommended thresholds.
- image_metrics object
  An object with three properties indicating the overall picture quality.
  - underexposure number(0-1)
    It indicates loss of shadow detail (closer to 0 is better).
  - overexposure number(0-1)
    It indicates loss of highlight detail (closer to 0 is better).
  - sharpness number(0-1)
    It indicates intensity of motion blur (closer to 1 is better).
  - color number(0-1)
    Indicates if there is a color degradation (close to 0 is better).
- time_taken number
  Inference time taken in seconds.
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
415 The content type or encoding is not valid.

{
  "total_faces": 1,
  "faces": [
    {
      "landmarks": {
        "right_eye": [
          77,
          159
        ],
        "left_eye": [
          110,
          157
        ],
        "nose": [
          96,
          180
        ],
        "mouth_right": [
          81,
          188
        ],
        "mouth_left": [
          108,
          187
        ]
      },
      "bounding_box": [
        58,
        117,
        125,
        208
      ],
      "face_metrics": {
        "underexposure": 0.3027245104312897,
        "overexposure": 0.1076354011893272,
        "sharpness": 0.3013559,
        "color": 0.02348230945,
        "rotation": 10.212483049
      },
      "liveness_score": 0.9935932755470276
    }
  ],
  "default_thresholds": {
    "sharpness": 0.07,
    "underexposure": 0.7,
    "overexposure": 0.65,
    "liveness": 0.7,
    "color": 0.61,
    "rotation": 68.2
  },
  "image_metrics": {
    "underexposure": 0.3027245104312897,
    "overexposure": 0.1076354011893272,
    "sharpness": 0.3013559,
    "color": 0.02348230945
  },
  "time_taken": 0.7423423
}

# Face Compare

The face compare method accepts two image files for similarity comparison.

The model will use the largest face (biggest bounding box area) on each source. Our face detection and recognition models do not consider faces that are not completely inside the given image input. For best results consider using only non-occluded faces.

TIP

We recommend using the key default_thresholds to verify similarity.

Headers
Authorization REQUIRED / string (jwt token)

Body

If comparing the faces between 2 images:

image_file1 string (binary)
image_file2 string (binary)
client_declaration_enduser_consent boolean (true/false)

If comparing an enrolled face with an image:

image_file string (binary)
user_token string
client_declaration_enduser_consent boolean (true/false)

POST https://api.getperse.com/v0/face/compare

$ curl \
 -X POST https://api.getperse.com/v0/face/compare \
 -H "Content-Type: multipart/form-data" \
 -H "Authorization: Bearer <string>" \
 -F "[email protected]" \
 -F "[email protected]" \
 -F "client_declaration_enduser_consent=boolean"

Response

200 object
The Compare object

defaultThresholds object
An object that contains default and recommended thresholds to verify similarity.
- similarity number
  Indicates the recommend threshold for similarity comparison.
- liveness number
  Indicates the recommended threshold for liveness verification.
similarity number
Similarity score between the two compared faces on source files. Higher similarity scores imply higher probability that both faces are from the same person.

liveness_score number
The liveness score indicates the probability that the received images where captured in a 'live' environment. Higher scores indicate greater confidence that images are 'live'.

time_taken number
Inference time taken in seconds
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
422 Face was not found on sent image.
415 The content type or encoding is not valid.

{
    "similarity": 95.0,
    "liveness_score": {
        "image_file1": 0.16,
        "image_file2": 0.16
    },
    "time_taken": 0.664,
    "status": 200,
    "default_thresholds": {
        "similarity": 75,
        "liveness": 0.7
    }
}

# Voice

# Voice Compare

The voice compare method accepts two audios files for similarity comparison.

Currently we only accept .wav or .ogg files.

Headers
Authorization REQUIRED / string (jwt token)

Body

audio_file1 string (binary)
audio_file2 string (binary)
client_declaration_enduser_consent boolean (true/false)

POST https://api.getperse.com/v0/voice/compare

$ curl \
 -X POST https://api.getperse.com/v0/voice/compare \
 -H "Content-Type: multipart/form-data" \
 -H "Authorization: Bearer <string>" \
 -F "[email protected]" \
 -F "[email protected]" \
 -F "client_declaration_enduser_consent=boolean"

Response

200 object
The Compare object

similarity number
Similarity score between the two compared audios on source files. Higher similarity scores imply higher probability that both faces are from the same person.

time_taken number
Inference time taken in seconds
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
415 The content type or encoding is not valid.

{
    "similarity": 0.6547079690280866,
    "time_taken": 0.744,
    "status": 200
}

# Enrollment

We save biometric facial features from enrolled faces for future use. The enrollment endpoints allow you to create, update, delete and list enrolled faces.

When enrolling or updating an user, the model will extract the facial features of the largest face from the received image file.

Faces that are not completely inside (partial/occluded) the image will not be considered.

In order to ensure that enrolled faces perform well on our face recognition models, faces with underexposed or overexposed values greater than their respective thresholds will not be considered. The following error codes are returned in this case:

image_underexposed

image_overexposed

Headers
Authorization REQUIRED / string (jwt token)

# Enroll User

This endpoint is responsible for creating new enrollments.

When a new face is enrolled, the endpoint returns the enrollment user_token.

Headers
Authorization REQUIRED / string (jwt token)

Body
image_file string(binary)
client_declaration_enduser_consent boolean (true/false)

POST https://api.getperse.com/v0/face/enrollment

$ curl \
 -X POST https://api.getperse.com/v0/face/enrollment \
 -H "Content-Type: multipart/form-data" \
 -H "Authorization: Bearer <string>" \
 -F "[email protected]" \
 -F "client_declaration_enduser_consent=boolean"

Response

200 object

user_token number
The user_token of the enrolled face

time_taken number
Inference time taken in seconds
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
422 Face was not found on sent image.
415 The content type or encoding is not valid

{
    "user_token": "9d0db3d4-4474-46e8-adb2-5bdafdc73c78",
    "time_taken": 0.286,
    "status": 200
}

# Delete User

Use this endpoint to delete an enrollment.

This endpoint expects an user_token in the url.

Headers
Authorization REQUIRED / string(jwt token)

DELETE https://api.getperse.com/v0/face/enrollment/<user_token>

$ curl \
 -X DELETE https://api.getperse.com/v0/face/enrollment/<user_token> \
 -H "Authorization: Bearer <string>"

Response

200 object

time_taken number
Inference time taken in seconds
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
422 Face was not found on sent image.
415 The content type or encoding is not valid

{
    "time_taken": 0.186,
    "status": 200
}

# List Users

Use this endpoint to get the complete list of the created user_tokens

Headers
Authorization REQUIRED / string (jwt token)

GET https://api.getperse.com/v0/face/enrollment/list

$ curl \
 -X GET https://api.getperse.com/v0/face/enrollment \
 -H "Authorization: Bearer <string>"

Response

200 object

user_tokens list
The list containing all user_tokens

total_users number
Total number of enrollments

time_taken number
Inference time taken in seconds
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
422 Face was not found on sent image.
415 The content type or encoding is not valid

{
    "user_tokens": [
        "1f7bb31a-acbd-4519-bdaf-492b15b40343",
        "2a330ecf-cead-438d-b2d7-5a195ae83eb8",
        "3b78ccd2-2ce8-4558-8c8c-d27e5f8c9a04",
        "9d0db3d4-4474-46e8-adb2-5bdafdc73c78",
        "a0418e93-e672-44de-862f-b80093725f96",
        "b22fdd13-a8c9-4c29-9614-f7d6c2f00c64",
        "ca5017de-ad6d-4425-8409-c81c9c0cb615"
    ],
    "total_users": 7,
    "time_taken": 0.07,
    "status": 200
}

# Update User

Use this endpoint to update a face enrollment with a new face image.

It receives an user_token and an image file to extract the biometric data. The user_token must have already been created.

Headers
Authorization REQUIRED / string (jwt token)

Body
image_file string (binary)
user_token string
client_declaration_enduser_consent boolean (true/false)

PUT https://api.getperse.com/v0/face/enrollment

$ curl \
 -X PUT https://api.getperse.com/v0/face/enrollment \
 -H "Content-Type: multipart/form-data" \
 -H "Authorization: Bearer <string>" \
 -F "[email protected]" \
 -F "user_token=<user_token>" \
 -F "client_declaration_enduser_consent=boolean"

Response

200 object

user_token string
The user_token of the updated enrollment

time_taken number
Inference time taken in seconds
400 The request was unacceptable, often due to a missing required parameter.
401 Session token is missing or invalid.
422 Face was not found on sent image.
415 The content type or encoding is not valid

{
    "user_token": "33d2e55f-8568-4f0f-9dcd-830d4fd445c6",
    "time_taken": 0.483,
    "status": 200
}

← Essentials