Our Docker image can run on x86-64 CPU.

Follow the instructions below to run the server docker.

As the first step, you need to load the Docker image from the provided file.

docker load -i opencv-fr-server.tar

After loading the image, you can start the server via the script below. This script will start a docker container with the Server image and copy the license and server-config information into that container:

./start-docker-with-license.sh

Once the server is running, you can access the API documentation/OpenAPI Swagger Docs page by going to a browser on the local machine via:

http://localhost:7777/docs

The Swagger Docs page is useful to test the web APIs from your browser. The Swagger framework allows developers to create interactive, machine and human-readable API documentation. It is the framework that REST API developers are most familiar with.

We also provide RapiDoc documentation that is better looking and easier to read:

http://localhost:7777/rapidoc

Every time a Docker container is restarted, it assumes a new ID. Since only 5 concurrent IDs are allowed (by default) in the license, you might encounter an error if you frequently start/stop the Docker images. Thus, it is recommended to start a Docker image only once and let it run.

With a fast setup, easy deployment, and low-maintenance architecture, Seventh Sense’s solution allows businesses to integrate cutting-edge face recognition capabilities with minimum operational complexity.

This document is an easy-to-implement guide for the OpenCV FR Server.

The OpenCV FR Server bundle that you have received consists of the following. Unzip the bundle to get started with the server:

1. Server docker tar file

2. license file

3. server-config file

4. start script to run the server docker

Pre-requisites

You need AMD / Intel bare metal machine / VM running Ubuntu 24.04 or Windows 11 server, and with Docker installed. At least 8GB of free RAM and 4 CPU cores are needed for the server. The server container image is available for x86-64 CPU(Linux/Windows) .

OpenCV FR Server includes below functions

• • Create collection

  • Delete collection

  • Get collection list

• • Enroll/Update a single person - liveness check available

  • Enroll/Update a batch of persons

  • Delete a person

  • Get a single or list of person

• • 1:N face search - liveness check available

  • 1:N face verification with a given person_id - liveness check available

  • N:N face search

Before performing Face Search (1:N, N:N), you first need to create a collection and enroll the persons in a specific collection.

Each collection is a table, collection name should be unique, it’s not allowed to create two collections with the same name.

Upon a collection being created, the collection name is not allowed to change. you can delete a collection, in this case, all enrolled persons within the collection will be deleted as well, so please be careful.

Create collection

POST /collection

This endpoint is to create a collection

Headers

Body

Response

Delete a collection

DELETE /collection

This endpoint is to delete a collection.

Headers

Body

Response

The licensing for the server is governed by a license file called server.lic. This file is located in the root folder of the distribution bundle.

The server.lic file determines quotas and limits for the system. During development, the initial file should provide enough quotas for your needs. As you approach a production deployment, please contact Seventh Sense for a review of your quota needs.

When the server is running, it offers several end-points that can be called via HTTP clients in a language of your choice.

To access these server end-points, please use your api_key

A random API key was included in the server-config.toml file mentioned in the previous section. Including it in requests using the x-api-key header will help authorize your requests.

Assuming that you have been able to successfully start the Docker and access the Swagger Docs page via:

http://localhost:7777/docs

The following describes how to use the Swagger Docs page. The Swagger Docs page makes http(s) calls via your browser. Hence, everything detailed below can also be accomplished using an http library in a programming language of your choice.

The page also provides cURL commands that you can execute from the command line to send requests and receive responses.

Authorization

Each API end-point in the Swagger Docs page requires an x-api-key header for authorisation.

For your convenience, the Swagger Docs page allows you to authorise via the UI in a browser.

This is demonstrated in the next section.

Upon opening the Swagger Docs page in the browser, you should see the Authorize button on the top right:

Now we can use the Swagger Docs page to interact with the API.

Face Recognition Use Cases

Below are key use cases for each feature:

1. Face Search (1:N, N:N) – Identify a person from a collection/database

Face Search allows the identification of individual(s) by searching their face against a database of enrolled users.

Sample Use Cases:

• Automated Attendance Checking – Verify and record employee/student attendance without requiring manual check-ins, reducing fraud and streamlining workforce management.

• Customer Onboarding – Match a new customer’s ID photo, face and/or photo against an ID database to prevent identity fraud.

• Smart Access Control – Grant access to employees or VIPs by registering and verifying their faces.

• Law Enforcement & Security – Identify persons of interest from CCTV footage.

• Casino Security & VIP Player Identification – Identify known fraudsters, excluded gamblers, or VIP guests in real time to enhance security.

How It Works:

1. User submits an image with single or multiple faces

2. The system searches for match(es) in the database

3. If matches are found, the system returns the identified person(s) with a confidence score.

2. Face Compare (1:1) – Verify if two faces belong to the same person

Face Compare allows the authentication of identities by comparing two face images and determining if they are the same person.

Use Cases:

• eKYC & Identity Verification – Match a user’s selfie with their government-issued ID photo to authenticate identity during onboarding.

• Passwordless Authentication & Secure Logins – Replace traditional passwords with facial authentication for secure app access.

• Border Control & Travel – Compare a traveler’s live face with their passport or visa photo for automated identity verification.

• Payment & High-Value Transactions – Verify users for banking transactions to prevent fraud.

How It Works:

1. User provides two face images.

2. The system computes a similarity score.

3. If the score is above a predefined threshold, the faces are considered a match.

3. Liveness Detection – Prevent spoofing & identity fraud

Liveness Detection ensures that the face being analyzed belongs to a live person, not a photo, video, or 3D mask.

Use Cases:

• Remote Attendance Checking – Ensure employees, students, or participants are physically present during check-ins, preventing fraudulent logins using photos or videos.

• eKYC & Identity Verification – Prevent identity fraud by ensuring that a real person is taking the selfie during onboarding.

• Fraud Prevention in Fintech & Banking – Block fraudulent transactions by ensuring a live user is making a request, not a deepfake or stolen photo.

• E-Government Services – Secure digital identity verification for national ID programs and voting systems.

• Online Exam Proctoring – Verify student presence in remote exams and prevent cheating using pre-recorded videos or fake faces.

How It Works:

1. User submits a photo for Liveness Detection as part of one of the following functions: Person Enrollment, Face Search (1:N), or Face Compare (1:1).

2. The system performs Liveness Detection alongside Face Recognition to verify identity and ensure the user is physically present.

3. If both Face Recognition and Liveness Detection pass, the system approves the action (e.g., enrolls the user, confirms identity, or logs attendance).

Why Choose Seventh Sense?

✅ Top ranked on NIST, no need for expensive GPUs. ✅ Fast setup, easy deployment in minutes. ✅ Works efficiently with millions of Faces. ✅ Privacy-first & GDPR-compliant.

The server is configured via a file named server-config.toml. This file is included in the root of the distribution package that you have received and was automatically used when you started the server. You can, however, customize the values in this file and then restart the server. Below are the important configurations-

# The following line defines the API key to access the server end-points.
api_key = "mykey"

################################### Data Security Secret ####################################
# The following line defines a secret used to protect your data at rest and ensures
# there is no correlatability between your own data and someone else's who is using this
# product. Even if your database layer is compromised, protecting this secret will thwart
# many forms of attack vectors. This secret cannot be changed without re-enrolling all 
# your data again. For secret rotation, it is suggested you re-enroll your entire data
# from time to time and point to a new instance while retiring the instance with the old
# secret.
#
# IMPORTANT NOTE: person_id and person_name are stored in plain text and are searchable.
# For full privacy, it is sugggested that you use UUIDs for person_id and skip storing
# the name where it is not neccessary. This is a trade-off between the convenience of 
# search and the privacy of non-correlatibility that you can consider to suit your
# use-case. It is also suggested that you use UUIDs for collection names while
# maintaining a separate database that maps those UUIDs to meaningful groups.
#
# This product stores Renewable Biometric References as per the below standard:
# Biometric information protection - ISO/IEC 24745:2022:
# https://www.iso.org/standard/75302.html
#
# The secret that you are setting below corresponds to Auxiliary Data as per the
# standard.
data_security_secret = "changethis"

# Change the following line to define another interface for the server to listen on.
ip = "0.0.0.0"

# Max request size in MB. Change this to restrict request size.
max_payload_size = 5

# Uncomment one of the following lines to define the database to use.
# The default is "database/opencv-fr-database" (this uses the local file system).

# Local file system:
conn_str = "database/opencv-fr-database-new"

# AWS S3:
#conn_str = "s3://bucket/path"

# Uncomment and set the following lines if you are using AWS S3.
# aws_access_key_id = "my-access-key"
# aws_secret_access_key = "my-secret-key"
# aws_session_token = "my-session-token"

############################### Read consistency interval ###################################

# The interval at which to check for db updates from other instances. If more than this
# duration has passed since the last read, the read will check for updates from other
# instances.

# 0s (Strong consistency): The database checks for updates on every read. 
# This provides the strongest consistency guarantees, ensuring that all instances see the
# latest committed data. However, it has the most overhead. This setting is suitable when 
# consistency matters more than having high QPS.

# ns (Eventual consistency): The database checks for updates every n seconds. This
# provides eventual consistency, allowing for some lag between write and read operations.
# Changes made on one instance may not be immediately visible on another instance. This
# setting is suitable when having high QPS is more important than consistency.

# The default is "10s" which allows for new data inserted on one instance to be visible
# on other instances at most 10 seconds later. Change this value to suit your needs to
# balance consistency and performance.
conn_read_consistency_interval = "10s"

################################## Index retrieval tuning ###################################

# Indexing is recommended only when your collection is larger than 1,000,000 persons.
# When using an index, face search can miss some items. Having no index means the search
# will be slower but it will also be exhaustive and not miss any items. If you have more
# than a million items in a collection, you can create an index. When using an index,
# tuning the following will allow you to refine your search results according to your
# dataset distribution.

# The number of probes determines the distribution of vector space. While a higher number
# enhances search accuracy, it also results in slower performance. Typically, setting
# nprobes to cover 5–10% of the dataset proves effective in achieving high recall with
# minimal latency.

conn_n_probes_percentage = 10

# Refine the results by reading extra elements and re-ranking them in memory. A higher
# number makes the search more accurate but also slower. Please see:
# https://lancedb.github.io/lancedb/faq/#how-can-i-speed-up-data-inserts
conn_refine_factor = 50

# The time to wait before allowing another optimize or indexing job if one is currently
# running on a particular collection
conn_job_wait_time_sec = 3600

If you change the values in server-config.toml, you will need to stop the container and restart it again.

First list the containers:

> docker ps

After observing the value for CONTAINER ID, from the output of docker ps command, you can stop it using:

docker stop 336180357b1d

Within a collection, Face Search API allows you to search for previously registered persons using an image with a single that is obtained at a later time. The search is performed using a deep learning model trained on millions of face images. The search results are ranked by the similarity score, which is a number between 0 and 1, where 1 is a perfect match and 0 is a perfect mismatch. The max_results parameter is optional and allows you to control the maximum number of returned results. By default, it is set to 1, but you can customize this number for your specific use case.

If multiple faces are been searched, the search results are returned in order of decreasing similarity score, as long the specified min_score threshold (default is 0.7) is met.

1:N Face Search

POST /face-search

This endpoint is for 1:N search of one face in an image within a collection

Headers

Body

N:N Face Search

POST /multi-face-search

<This endpoint is for N:N search multiple faces in an image within a collection>

Body

Response

To prevent fraud using high-resolution printouts, masks, or video replays, the liveness image imposes stricter requirements on the image. Liveness image requirement:

Our API processes the area around the face, so the optimal resolution will depend on the image content. Assuming a portrait orientation, with the face centered and taking at least 1/4 of the image area, the minimum image resolution is SVGA (600x800). In general, images captured in higher resolution will result in better accuracy.

• The minimum size of a face box that can be processed is 150x150 pixels.

• The padding between the face box and the image's borders should be at least 15 pixels.

• The distance between the pupils on the face should be at least 50 pixels.

• The out-of-plane rotation angle (face pitch and yaw) should be no more than ±30 degrees.

• There should only be one main face on the image. It should be fully visible within a frame and fully

• Fish-eye lenses and sunglass images are not supported.

Face Compare API allows you to compare two face images to determine if they correspond to the same person. A score higher than 0.7 is a good indicator that the two images belong to the same person.

You can also use a score of 0.67 or higher if the images are of the same person but taken at different times (years apart). The score is a number between 0 and 1, where 1 is a perfect match and 0 is a perfect mismatch. The score is calculated using a deep learning model trained on millions of face images.

If the liveness check is enabled in the provided server, you can check the liveness with the face compare feature in a single API call.

1:1 Face Compare

POST /compare

This endpoint is for 1:1 face compare, no person enrollment needed

Headers

Body

Response

Bulk Enroll or Update Persons

PUT /persons

This endpoint is to enroll or update persons in bulk.

Headers

Body

Response

[
  {
    "code": "string",
    "message": "string",
    "metadata": {
      "additionalProp1": "string",
      "additionalProp2": "string",
      "additionalProp3": "string"
    }
  }
]

{
  "code": "ERR_INVALID_COLLECTION_NAME",
  "message": "Collection names can only contain alphanumeric characters, underscores, hyphens, and periods."
}

{
  "code": "ERR_API_KEY_NOT_PRESENT",
  "message": "The API key is missing from the request."
}

{
  "code": "ERR_API_KEY_NOT_VALID",
  "message": "The API key is not valid."
}

{
  "code": "ERR_NOT_FOUND",
  "message": "The requested entity could not be found."
}

{
  "code": "ERR_UNPROCESSABLE_CONTENT",
  "message": "The posted JSON is malformed or contains fields that are not of the correct type."
}

{
  "code": "ERR_DATABASE_ERROR",
  "message": "An error occurred while connecting with the database, please retry your request later."
}

Following the collection(s) creation, let's start enrolling some person(s) in the collection.

Add a person

PUT /person

Headers

Body

Response

{
  "face_base_64": "string",
  "metadata": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "person_id": "string",
  "person_name": "string"
}

{
  "code": "ERR_INVALID_COLLECTION_NAME",
  "message": "Collection names can only contain alphanumeric characters, underscores, hyphens, and periods."
}

{
  "code": "ERR_API_KEY_NOT_PRESENT",
  "message": "The API key is missing from the request."
}

{
  "code": "ERR_API_KEY_NOT_VALID",
  "message": "The API key is not valid."
}

{
  "code": "ERR_NOT_FOUND",
  "message": "The requested entity could not be found."
}

{
  "code": "ERR_PERSON_ALREADY_EXISTS",
  "message": "Another person exists with a similar face. Check metadata for the person_id of the duplicate.",
  "metadata": {
    "person_id": "c96a1bc7-4c4e-497e-897f-c448a4a4be6a"
  }
}

{
  "code": "ERR_LIVENESS_ERROR",
  "message": "A liveness error occurred. Please check the supplied image and the error metadata.",
  "metadata": {
    "code": "FACE_NOT_LIVE || .. || UNKNOWN_ERROR"
  }
}