Quick Start

Get from zero to your first face match in about five minutes. You can do everything from the web console at solutions.virtisha.com, or from the REST API — both are shown side by side below.

Step 1 · Create an account

Sign up on the registration page with a username, email, and password. Every new account starts on the Free plan and is issued an api_key and api_secret instantly — you'll find them any time on your Profile.

Prefer the API?

curl -X POST https://solutions.virtisha.com/auth/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "username": "acme",
    "password": "your-password"
  }'

Response:

{
  "message": "User registered on the Free plan. Contact enquiry@virtisha.com to upgrade.",
  "api_key": "1f6e1974f57eaca755488b5f7c2ba20b",
  "api_secret": "4055ad57275a0862296425734ba69031e593e5d48015820a70126b0443dda80a",
  "plan": "free",
  "subscription": { "plan": "free", "status": "active" }
}

Step 2 · Sign in

Log in to the console at /web/login to reach your dashboard. Over the API, logging in returns a short-lived bearer token (valid 24 hours) plus a live snapshot of your plan usage:

curl -X POST https://solutions.virtisha.com/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "password": "your-password" }'

The recognition endpoints use your api_key/api_secret headers, so you don't strictly need the token — it's mainly for GET /user/ and reading account info.

Step 3 · Create a gallery

A gallery is a private collection of faces. Matching only ever searches the gallery you choose (or all of yours), and no other account can see your faces. Every account comes with a Default gallery; create more from Profile → My galleries in the console (for example Employees or VIP guests).

When you enroll or match over the API, pass the gallery by name or id in the gallery field. Omit it (or send null) to use your Default gallery when enrolling, or to search across all your galleries when matching.

Step 4 · Enroll a face

In the console: open Match a Face, upload a photo, fill in the person's name (and optional reference ID), pick a gallery, and click Save to gallery.

Over the API: POST /save/

curl -X POST https://solutions.virtisha.com/save/ \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "Meera Kapoor",
    "userId": "EMP-001",
    "image_b64": "",
    "active": 1,
    "gallery": "Employees"
  }'

On success you get back the stored record. If the same person (or userId) is already in the gallery, the response reports the existing face instead of creating a duplicate:

{
  "status": true,
  "message": "Face saved successfully",
  "responsePacket": { "user": { "_id": "...", "name": "Meera Kapoor",
      "userId": "EMP-001", "gallery_name": "Employees", "Active": 1 } }
}

active: 1 includes the face in "active-only" searches; use 0 to keep it enrolled but excluded from those.

Step 5 · Match a face

In the console: on Match a Face, upload a photo, choose which gallery to search, and hit Find matches. You'll see ranked candidates with a similarity score for each.

Over the API: POST /detect/

curl -X POST https://solutions.virtisha.com/detect/ \
  -H "api_key: YOUR_API_KEY" \
  -H "api_secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "image_b64": "",
    "with_all": 1,
    "gallery": "Employees"
  }'

Every detected face is returned with its best match. A face whose top similarity is below the recognition threshold (0.50) comes back as "Unknown":

{
  "status": true,
  "message": "Face detect successfully",
  "responsePacket": {
    "detections": [
      {
        "name": "Meera Kapoor",
        "userId": "EMP-001",
        "similarity": 0.91,
        "det_confidence": 0.88,
        "Active": 1
      }
    ]
  }
}

• with_all: 1 searches every face in scope; 0 restricts to active faces only.
• similarity is cosine similarity from 0 to 1 — higher is a closer match.
• Leave gallery out to search across all your galleries.

Check your usage

See your live plan consumption any time on the Profile page, or via the API — this call does not count against your quota:

curl https://solutions.virtisha.com/auth/usage/ \
  -H "api_key: YOUR_API_KEY" -H "api_secret: YOUR_API_SECRET"

Need more? Upgrades to Basic, Pro, or Enterprise are handled by our team — email enquiry@virtisha.com. See all tiers in the User Guide.

Encoding images to Base64

The API takes images as Base64 strings (raw Base64, or a data: URL — both work).

Python

import base64
with open("face.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

JavaScript (browser)

const buf = await file.arrayBuffer();
const image_b64 = btoa(String.fromCharCode(...new Uint8Array(buf)));

Command line

base64 -w0 face.jpg          # Linux
base64 -i face.jpg           # macOS

Reference card