Face Recognition System — User Guide

Getting Started

What is this system?

This is a face recognition platform that allows you to:

• Store and manage face images
• Search for faces in your database
• Recognize faces automatically
• Track detection history
• Integrate face recognition into your applications via API

System requirements

• Modern web browser (Chrome, Firefox, Safari, Edge)
• Internet connection
• Valid email address for registration

Registration & Login

Creating an account

1. Visit the login page
   • Go to the system URL in your web browser
   • Click "Register" or "Sign Up"
2. Fill in your details
   • Email: your email address (must be unique)
   • Username: choose a username
   • Password: create a strong password
3. Receive your API credentials
   • API Key: a 32-character code (e.g., f1377d82a0e43f4a7682b1af582dea3e)
   • API Secret: a 64-character code
4. Automatic subscription
   • You're automatically enrolled in the Free Plan
   • You can upgrade later if needed

Important: save these credentials securely — you'll need them to use the API. Never expose API credentials publicly.

Logging in

1. Go to the login page
2. Enter your email and password
3. Click "Login"
4. You'll be redirected to your dashboard

Dashboard

When you log in, you'll see your main dashboard with:

Statistics cards

• Total Faces: total number of faces in your database
• Known Faces: faces that have been identified/tagged
• Active Faces: faces currently active for recognition
• Recent Detections: detections made in the last 24 hours

Recent faces section

• Shows the 10 most recently added faces
• Click on any face to view details

Quick actions

• Add Face: upload a new face to your database
• Search Face: search for a face in your database
• View All Images: browse all stored faces
• View Detections: see detection history

Subscription Plans

Choose a plan based on your usage and scalability needs.

What is a "request"?

A request is counted every time you:

• Search for a face
• Add a new face
• Recognize a face via API
• Update face information
• Delete a face

Understanding rate limits

• Hourly — prevents burst overload (resets every hour)
• Daily — controls daily usage (resets at midnight UTC)
• Monthly — your main quota (resets every 30 days)

Checking your usage

Option 1: via API

BASE="https://solutions.virtisha.com"

curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "$BASE/auth/rate-limit-status/"

Response example:

{
  "subscription_plan": "Free",
  "total_requests": 156,
  "limits": {
    "hourly": {
      "used": 12,
      "limit": 200,
      "remaining": 188
    },
    "daily": {
      "used": 45,
      "limit": 200,
      "remaining": 155
    },
    "monthly": {
      "used": 156,
      "limit": 2000,
      "remaining": 1844
    }
  }
}

Option 2: via dashboard

• Open your dashboard
• The top-right shows: Requests: 156 / 2000 this month

Face Database

Adding a face — via web interface

1. Go to the dashboard
   • Click the "Add Face" button
2. Upload an image
   • Click "Choose File" or drag & drop
   • Supported formats: JPG, PNG
   • The image must contain a visible face
3. Enter details
   • Name: person's name
   • User ID: unique identifier (optional)
   • Active: check if you want this face recognized immediately — active faces are used for recognition; inactive faces are stored but not used for matching
4. Save
   • Click "Save Face"
   • The face is processed and added to the database
   • You'll see a confirmation message

Adding a face — via API

BASE="https://solutions.virtisha.com"

curl -X POST "$BASE/save/" \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "BASE64_ENCODED_IMAGE",
    "userId": "USER123",
    "user_name": "John Doe",
    "active": 1
  }'

Viewing all faces

1. Navigate to the Images page
   • Click "Images" in the menu
2. Filter options
   • All: shows all faces
   • Known: shows identified faces
   • Unknown: shows unidentified faces
   • Active: shows only active faces
3. Search
   • Use the search box to find by name or user ID
   • Search is case-insensitive
4. Pagination
   • 20 faces per page
   • Use "Previous" and "Next" buttons to navigate

Viewing face details

Click on any face image and you'll see:

• Full-size image
• Name and user ID
• Status (Active/Inactive)
• Detection confidence score
• Date added
• Facial features data

Editing a face

1. Open the face details page
2. Click the "Edit" button
3. Update information: change the name, change the user ID, or toggle the active status
4. Click "Save Changes"

Deleting a face

1. Open the face details page
2. Click the "Delete" button
3. Confirm deletion

Note: this action cannot be undone!

Search Faces

How face search works

When you upload an image:

1. The system detects the face in the image
2. Extracts facial features
3. Compares them against all faces in the database
4. Returns matches sorted by similarity score

Using the search feature

1. Go to the Search page
   • Click "Search" in the menu
2. Upload a search image
   • Click "Choose File" or drag & drop
   • The image should clearly show the face
3. Click "Search"
   • The system processes the image
   • Results appear within seconds
4. View results
   • Shows the top 10 matches
   • Each result shows: the match image, name and user ID, similarity score (0-100%) and status (Active/Inactive)

Understanding similarity scores

• 90-100%: excellent match (very likely the same person)
• 80-89%: good match (probably the same person)
• 70-79%: moderate match (possibly the same person)
• 60-69%: low-confidence match (might be the same person)
• Below 60%: not a reliable match

Search tips

Good practices:

• Use clear, well-lit photos
• The face should be facing forward
• Avoid sunglasses or masks
• High-resolution images work best

Avoid:

• Blurry or dark images
• Extreme angles
• Multiple faces in one image (the system uses the first detected face)
• Very small face images

Detection History

What is detection history?

Every time the system recognizes (or attempts to recognize) a face, it creates a detection record.

Accessing detection history

1. Click "Detections" in the menu
2. You'll see a list of all detection events

Understanding detection records

Each record shows:

• Input Image: the image that was searched
• Matched Face: the face that was found (if any)
• Similarity Score: how confident the match is
• Name & User ID: who was recognized
• Timestamp: when the detection occurred

Filtering detections

Filter options:

• All: show all detections
• Recognized: only successful matches
• Unknown: only unrecognized faces
• High Confidence: matches with similarity above 80%
• Low Confidence: matches with similarity below 50%

Date range:

• Select "From" and "To" dates
• Click "Filter" to apply

Search:

• Search by name or user ID

Exporting detection history

(Feature coming soon)

• Export to CSV
• Export to PDF report
• Email scheduled reports

API Guide

What is the API?

The API (Application Programming Interface) allows you to integrate face recognition into your own applications, websites or systems.

Your API credentials

You received these when you registered (example values, line-wrapped for display):

api_key (32 characters):
f1377d82a0e43f4a7682b1af582dea3e

api_secret (64 characters):
f0a48b922f4550aa857e787a92583f77
12edbc364dccb3c21c7d6d5cb3e0e8b9

Security: never share these credentials, and never commit them to public code repositories. If they're compromised, contact support immediately.

Getting an authentication token

For web/mobile apps, get a token first:

BASE="https://solutions.virtisha.com"

curl -X POST "$BASE/auth/login/" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "your_password"
  }'

Response:

{
  "message": "Login successful",
  "token": "abc123def456...",
  "api_key": "f1377d82...",
  "api_secret": "f0a48b92...",
  "user": {
    "email": "your@email.com",
    "username": "yourname",
    "subscription_id": "..."
  }
}

Common API operations

1. Recognize a face

BASE="https://solutions.virtisha.com"

curl -X POST "$BASE/recognize/" \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "BASE64_ENCODED_IMAGE"
  }'

Response:

{
  "status": true,
  "message": "Face recognized",
  "responsePacket": {
    "name": "John Doe",
    "userId": "USER123",
    "similarity": 0.95,
    "Active": 1
  }
}

2. Add a face

BASE="https://solutions.virtisha.com"

curl -X POST "$BASE/save/" \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "BASE64_ENCODED_IMAGE",
    "userId": "USER123",
    "user_name": "John Doe",
    "active": 1
  }'

3. Check your usage

BASE="https://solutions.virtisha.com"

curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "$BASE/auth/rate-limit-status/"

4. Get user info

BASE="https://solutions.virtisha.com"

curl -X GET \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "$BASE/user/"

Encoding images to Base64

Python:

import base64

with open("image.jpg", "rb") as f:
    data = f.read()

encoded = base64.b64encode(data)
text = encoded.decode("utf-8")

JavaScript:

const fs = require('fs');
const buf = fs.readFileSync('image.jpg');
const b64 = buf.toString('base64');

Command line (Linux/Mac):

base64 image.jpg

Rate Limits

Why rate limits exist

Rate limits prevent:

• System overload
• Abuse
• Excessive costs
• Performance degradation

What happens when you hit a limit?

You'll receive an error (wrapped for display):

{
  "detail": "Hourly API limit
  exceeded. Limit: 200/hour.
  Resets in 45 minutes."
}

HTTP status code: 429 (Too Many Requests)

Best practices

1. Monitor your usage
   • Check the rate-limit status regularly
   • Set up alerts when approaching limits
2. Implement retry logic

   import time
   
   def api_call_with_retry():
       try:
           return make_api_call()
       except RateLimitError:
           time.sleep(3600)  # wait 1 hour
           return make_api_call()

3. Batch operations
   • Process multiple faces in one session
   • Avoid making calls one at a time
4. Cache results
   • Store recognition results locally
   • Don't re-recognize the same face repeatedly
5. Upgrade if needed
   • If you're consistently hitting limits, consider upgrading your plan

Troubleshooting

1. "Invalid API credentials"

Problem: the API key or secret is incorrect.

Solutions:

• Check for typos in your credentials
• Ensure there are no extra spaces
• Get new credentials by logging into the dashboard
• Check you're using the right credentials for the right account

2. "No face detected in the uploaded image"

Problem: the system cannot find a face in the image.

Solutions:

• Ensure the face is clearly visible
• Check image quality (not too dark or blurry)
• Make sure the face is not too small in the image
• Avoid extreme angles
• Remove sunglasses or face coverings

3. "Rate limit exceeded"

Problem: you've hit your hourly, daily or monthly limit.

Solutions:

• Wait for the limit to reset
• Check when the limit resets: /auth/rate-limit-status/
• Upgrade your subscription plan
• Optimize your application to make fewer calls

4. "Invalid token"

Problem: your authentication token has expired or is invalid.

Solutions:

• Log in again to get a new token
• Implement automatic token refresh in your application
• Check the token was copied correctly

5. Low recognition accuracy

Problem: the system returns incorrect matches.

Solutions:

• Add more images of each person (different angles and lighting)
• Use high-quality images
• Ensure database faces are properly tagged
• Check the similarity-threshold settings

6. Slow performance

Problem: recognition takes too long.

Solutions:

• Check your internet connection
• Reduce image size before uploading
• Use compressed image formats (JPEG instead of PNG)
• Contact support if there's a system-wide slowdown

Getting help

Need assistance?

1. Check the documentation: review this guide thoroughly
2. Check API status: visit the status page for system outages
3. Contact support: email enquiry@virtisha.com and include:
   • Your username/email
   • A description of the problem
   • Steps to reproduce
   • Screenshots if applicable
   • Error messages

Appendix

API endpoints quick reference

HTTP status codes

• 200: success
• 400: bad request (check your data)
• 401: unauthorized (check credentials)
• 404: not found
• 422: validation error (check required fields)
• 429: rate limit exceeded
• 500: server error (contact support)

Glossary

• Base64: a way to encode binary image data as text
• Similarity Score: a number between 0 and 1 indicating how similar two faces are
• Active Face: a face that's currently used for recognition
• Known Face: a face that has been identified/tagged
• Detection: an instance of the system trying to recognize a face
• Feature Vector: a mathematical representation of a face used for comparison

Version & Support

Version history

Version 1.0 — October 2025

• Initial release
• Basic face recognition
• Rate limiting system
• Web dashboard
• API endpoints

Last updated: October 31, 2025

For the latest version of this documentation, visit https://solutions.virtisha.com.

Need help?

• Email: enquiry@virtisha.com
• Live chat: available on the dashboard
• Knowledge base: https://solutions.virtisha.com

We're here to help you succeed with face recognition!