# Introduction

This reference documents every object and method available in Perse's browser-side Javascript library, Perse.js.

You can use Perse's APIs to detect faces, gather feedback on image quality and compare the similarity between two faces. This SDK provides methods that help you authenticate users identity and directly communicate with Perse's API endpoints. The SDK also abstracts away the usage of common cases.

Check our project on npm (opens new window)

# 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

Perse.js encapsulates and manages API responses to return structures that are easier process.

It provides a message that can be used to give feedback to the user and also appears as a warning on browser console.

In order to know if the operation succeed, you can verify the status flag and the failure reason can be treated by using code.

The structure and codes are grouped on the following types:

# Returned Data Attributes

Whenever there is an error, 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.

status boolean
Boolean flag that indicates if operation succeed or not.

# Error Codes

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

The model could not find a face in at least one of the images. Please check the property image_metrics for insight on the image quality.

The source file is empty or not sent.

The image file type is not accepted by API.

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

The source file byte size is too large. Please send image files with less than 1 MB.

Person on sent images has low similarity value.

Image has a bad quality. It is overexposed, underexposed or not sharpened.

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 userToken.

  "message": "The source file is empty or wasn't sent.",
  "code": "empty_file",
  "status": false

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

# Including Perse

First you need to include the Perse javascript library into your project. Second, initialize the library in order to access Perse global variable.


NPM is the recommended installation method when building large scale applications with Perse. It pairs nicely with module bundlers such as Webpack or Browserify.

npm install @cyberlabsai/perse-sdk-js


You may also simply download and include Perse.js using a script tag. Perse will be registered as a global variable.

<script src="http://unpkg.com/@cyberlabsai/[email protected]">

# Initializing Perse

To get started you can use Perse.init("apiKey") to create an instance of the Perse object. The Perse object gives you access to the rest of Perse.js SDK methods.

Perse API authenticates your requests using an API key.

We are currently in Alpha version. You can request a test API Key by sending an email to [email protected]

import * as Perse from '@cyberlabsai/perse-sdk-js'