Quickstart

Quickstart

Get face recognition working in your app in under 5 minutes.

1. Start the server

   git clone https://github.com/drinkredwine/openbiometrics
   cd openbiometrics/engine && pip install -e . && python download_models.py
   cd ../api && uvicorn app.main:app --port 8000

   API docs at http://localhost:8000/docs (Swagger UI).

2. Install the SDK

   Node.js

   npm install openbiometrics

   Python

   pip install openbiometrics

3. Detect your first face

   Node.js

   import { OpenBiometrics } from 'openbiometrics';
   import { readFileSync } from 'fs';
   
   const ob = new OpenBiometrics({
     apiKey: 'any-value',
     baseUrl: 'http://localhost:8000',
   });
   
   const photo = readFileSync('photo.jpg');
   const result = await ob.faces.detect(photo);
   
   for (const face of result.faces) {
     console.log(`Age: ${face.demographics?.age}`);
     console.log(`Quality: ${face.quality?.overall_score.toFixed(0)}/100`);
   }

   Python

   from openbiometrics_sdk import OpenBiometrics
   
   ob = OpenBiometrics(
       api_key="any-value",
       base_url="http://localhost:8000",
   )
   
   result = ob.faces.detect("photo.jpg")
   for face in result["faces"]:
       print(f"Age: {face['demographics']['age']}")
       print(f"Quality: {face['quality']['overall_score']:.0f}/100")

   cURL

   curl -X POST http://localhost:8000/api/v1/detect \
     -F "image=@photo.jpg" | python -m json.tool

4. Verify two faces

   Node.js

   const id_photo = readFileSync('id_card.jpg');
   const selfie = readFileSync('selfie.jpg');
   
   const { is_match, similarity } = await ob.faces.verify(id_photo, selfie);
   console.log(is_match ? 'Identity confirmed' : 'Mismatch');

   Python

   result = ob.faces.verify("id_card.jpg", "selfie.jpg")
   if result["is_match"]:
       print(f"Identity confirmed ({result['similarity']:.1%})")

5. Build a watchlist

   Node.js

   await ob.watchlists.enroll(photo1, { label: 'Alice' });
   await ob.watchlists.enroll(photo2, { label: 'Bob' });
   
   const { matches } = await ob.watchlists.identify(unknownPhoto);
   for (const match of matches) {
     console.log(`${match.label}: ${(match.similarity * 100).toFixed(1)}%`);
   }

   Python

   ob.watchlists.enroll("alice.jpg", label="Alice")
   ob.watchlists.enroll("bob.jpg", label="Bob")
   
   result = ob.watchlists.identify("unknown.jpg")
   for match in result["matches"]:
       print(f"{match['label']}: {match['similarity']:.1%}")

What’s Next

• Active Liveness — challenge-response anti-spoofing with presets
• Document Processing — MRZ parsing and document scanning
• Video Analytics — real-time camera processing
• Events & Webhooks — subscribe to biometric events
• Docker deployment — containerized setup