The Perse API provides endpoints for biometric authentication using facial recognition, voice identification and anti-spoofing methods.
The API is organized around the 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. Evaluate the likelihood of a replay-attack. Compare similarity between two voices.
Learn more about
Perse (opens new window) TEST IT
Test endpoints are available using
Swagger UI playground. (opens new window) BUILDING FOR THE WEB?
Perse API authenticates your requests using a session token.
The authentication endpoint uses your API Key to create a session token. If you don't own an API Key, you can create an
account and get your API key
here. (opens new window)
Pay attention: Session tokens expires in 15 minutes. After expiration, you need to create a new session token
calling the authentication endpoint with your API Key.
All requests must include the session token in the
200: Authenticated successfully.
Session token used to authenticate requests to other Perse endpoints.
privateKey is missing on request body.
401: API key is invalid.
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.
Whenever an error is thrown, the server will return a JSON encoded response with the following structure.
A human-readable message providing more details about the error.
A simple string with the code message for programmatic error handling.
If the error is parameter-specific, the parameter related to the error will be shown inside the array.
The HTTP status of the request.
Inference time taken in seconds. Error Codes
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. no_face_biometric_data
User token was not found when comparing image with
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.
File formats: WAV, OGG
File size: no files larger than 1 MB.
End user Consent
In order to use the Perse API, it's necessary to ask the end user (the person on the image or on the audio file) for consent and inform it inside
Informing end user consent is required for every endpoint that uses biometric data. If consent is
false or empty, the request will not be processed.