User Guide

The complete reference for the Virtisha FRS platform — the web console and the REST API. If you're brand new, skim the Quick Start first, then use this guide for depth.

What the platform does

• Enroll faces into private, named galleries.
• Match a new photo against a gallery and rank candidates by similarity.
• Browse your enrolled faces, and review a history of every search and API detection.
• Integrate the same capabilities into your own apps over a REST API.

Recognition uses SCRFD face detection and landmark-aligned ArcFace embeddings, so matches stay reliable across pose, angle, and lighting changes. Everything is scoped to your account: no other user can see or search your faces.

Accounts & login

Anyone can create an account with a username, email, and password. New accounts:

• start on the Free plan automatically;
• receive an api_key and api_secret for the REST API immediately;
• get a Default gallery to enroll into right away.

Sign in at /web/login. Web sessions use a secure cookie and last 72 hours; API logins return a bearer token valid for 24 hours.

Dashboard

Your landing page after login. It shows:

• Stat cards — your gallery count, enrolled faces, searches run, and API detections.
• Recent searches — your latest matches with the best result and its score.
• Plan usage — API calls used this month and stored-face count against your plan limits.
• My galleries — quick links into each collection.

Galleries

Galleries are the heart of the system — a gallery is a private, named set of faces. Manage them under Profile → My galleries: create, rename, or delete (deleting a gallery removes its faces).

When you match, you choose a gallery to search, or search across all of yours. When you enroll, you choose which gallery the face joins. Typical setups: one gallery per site, per customer, per team, or per use-case.

Match a face

The Match a Face screen is where most work happens:

1. Upload a photo — drag & drop, browse, or paste from the clipboard.
2. Choose a gallery to search (or "All my galleries") and how many results to return.
3. Find matches — results are ranked by similarity, each with a score bar and the matched person's details.
4. Enroll on the spot — if the person isn't found, give them a name and save them into a gallery without leaving the page.

Reading similarity scores

The match threshold is 0.50 by default. For the best accuracy, enroll a clear, front-facing, well-lit photo of each person.

Faces library

The Faces screen lists everyone you've enrolled. Filter by gallery or active status, or search by name or reference ID. Open a face to see its record — gallery, enrollment date, detector score, and vector statistics — or delete it. The underlying 512-dimension embedding stays on the server and is never exposed through the API.

Searches & detections

Recent Searches logs every match you run from the console: the query image, the gallery searched, the best result, and whether it cleared the threshold. Filter by matched vs. no-match.

API Detections logs recognition calls made through /detect/ with your API keys, including the matched person and similarity. Filter by recognized/unknown, confidence, or date.

Profile & API keys

The Profile page holds:

• API credentials — your api_key and (reveal-to-view) api_secret, with copy buttons and a ready-to-run example.
• Usage meters — calls this month and stored faces vs. your plan limits.
• Galleries — create, rename, and delete collections.
• Plan — your current tier, with a contact link to upgrade.

Subscription plans

What counts as a call? Each /detect/ (match), /save/ (enroll), and each console match consumes one API call against your monthly quota. Reading your usage does not.

Admin console

Accounts with the administrator role get a Users & Plans section. From there an admin can review every account — plan, calls this month, faces, galleries, searches, last login — and open any user to see their recent activity, change their subscription, or enable/disable the account. Disabling an account immediately blocks its web and API access. This section is hidden for regular users.

API reference

Authentication

Send your credentials as headers on every recognition request:

api_key: YOUR_API_KEY
api_secret: YOUR_API_SECRET

Find them on your Profile. The account-info endpoint GET /user/ instead uses a bearer token from /auth/login/: Authorization: Bearer <token>.

Enroll a face — POST /save/

{
  "user_name": "Meera Kapoor",   // display name (required)
  "userId": "EMP-001",            // your reference id (optional, unique per account)
  "image_b64": "<base64>",        // JPG/PNG, one clear face
  "active": 1,                    // 1 = included in active-only searches
  "gallery": "Employees"          // name or id; omit for Default
}

Duplicate protection: if the userId already exists, or the same face is already in the gallery (similarity > 0.85), the response returns the existing record instead of enrolling twice.

Match a face — POST /detect/

{
  "image_b64": "<base64>",   // photo to identify (may contain several faces)
  "with_all": 1,             // 1 = all faces in scope; 0 = active only
  "gallery": "Employees"     // name or id; omit to search all your galleries
}

Returns one entry per detected face under responsePacket.detections, each with name, userId, similarity, det_confidence, and Active. Faces below the threshold come back as Unknown.

Other endpoints

• DELETE /remove/ — body { "face_id": "..." }; removes one of your faces.
• GET /auth/usage/ — your plan and current consumption (free, doesn't count).
• GET /auth/plans/ — the public plan catalog.
• GET /user/ — account info (bearer token).

Encoding images

# Python
import base64
image_b64 = base64.b64encode(open("face.jpg","rb").read()).decode()

Rate limits

Two limits protect the service and keep it fair:

• Per-minute — 30 (Free) to 600 (Pro) calls per minute. Exceeding it returns HTTP 429.
• Monthly quota — your plan's calls-per-month. When exhausted, calls return HTTP 429 until the next month or an upgrade.

Storing more than your plan's face limit returns HTTP 403 on /save/. Good practice: watch /auth/usage/, back off and retry on 429, and enroll one clean photo per person rather than many near-duplicates.

Troubleshooting

Appendix

HTTP status codes

Glossary

• Gallery — a private, named collection of enrolled faces.
• Enroll — add a face to a gallery so it can be matched later.
• Embedding — the 512-number vector that represents a face; compared by cosine similarity.
• Similarity — closeness of two faces, 0 to 1; ≥ 0.50 is treated as a match.
• Active — a flag that includes/excludes a face from active-only searches.

FRS platform · solutions.virtisha.com · updated 2026-07