# 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)


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)


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.

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

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.

The image file is empty or not sent.

The image file type is not accepted by API.

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 does not exist on backend.

User token was not found on update.

User token was not found when comparing image with user_token.

  "message": "The source image sent is empty",
  "code": "empty_file",
  "params": [
  "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.