# Introduction

The Perse API provides endpoints for biometric authentication using facial recognition and voice identification (coming soon).

The API is organized around RESTful message design pattern. It generates JSON-encoded responses with predictable content following standard HTTP response codes, authentications and verbs.

Using only a few lines of code, you can:

  • Detect the number of faces on a given image.
  • Evaluate the overall quality of an image.
  • Compare similarity between two faces.

Learn more about Perse (opens new window)

# LOOKING FOR A HOW-TO GUIDE?

Check out Perse open source libraries and example implementations on different backend languages:

Test endpoints are also available using Swagger UI playground (opens new window)

# BUILDING FOR THE WEB?

Please, take a look at the Javascript SDK available here

# Token

Perse API authenticates your requests using an API key. All requests must include the x-api-key key on its HEADER.

We are currently in Alpha version. You can create an account and get your API key here (opens new window)

# Errors

The Perse API uses the standard HTTP response codes to indicate success or failure of a request.

The status codes are grouped together under the following types:

  • 2xx: Successful codes.
  • 4xx: Error codes. This group of codes indicate errors related to the information provided on the request.
  • 5xx: Error codes. This group of codes indicate errors related to the server.
Show HTTP status code summary

200 - OK

Everything worked as expected.

400 - Bad request

The request was unacceptable, often due to a missing required parameter.

401 - Unauthorized

No valid API key provided.

415 - Unsupported Media Type

The content type or encoding is not valid.

422 - Unprocessable Entity

The parameters were valid, but the request failed.

500, 502, 503, 504 - Server Errors

Something went wrong on our side.

# Response Attributes

Whenever an error is thrown, the server will return a JSON encoded response with the following structure.

message string
A human-readable message providing more details about the error.

code string
A simple string with the code message for programmatic error handling.

params string
If the error is parameter-specific, the parameter related to the error will be shown inside the array.

status string
The HTTP status of the request.

time_taken number
Inference time taken in seconds.

# Error Codes

Some 400 errors that can be handled programmatically (e.g., no face detected) include an error code that briefly explains the error reported.

content_type_header_missing
The request header is missing the content-type key with a value of multipart/form-data

no_face_detected
The model couldn't find a face in at least one of the images. Please check the property image_metrics for insight on the image quality.

empty_file
The image file is empty or not sent.

invalid_file_type
The image file type is not accepted by API.

form_key_missing
The request is missing: image file(s) or token.

image_underexposed - Enrollment only
The image file received is too underexposed and could not be used for enrollment.

image_overexposed - Enrollment only
The image file received is too overexposed and could not be used for enrollment.

user_token_not_found
User token does not exist on backend.

image_id_invalid
User token was not found on update.

no_face_biometric_data
User token was not found when comparing image with user_token.

{
  "message": "The source image sent is empty",
  "code": "empty_file",
  "params": [
      "image_file1"
  ],
  "status": 400,
  "time_taken": 5000
}

# Image Requirements

File formats: JPG, PNG

File size: no files larger than 1 MB.

Image dimensions: For best performance we recommend images where faces are at least 200x200 pixels.