Node.js SDK

Node.js SDK

npm install openbiometrics

Initialize

import { OpenBiometrics } from 'openbiometrics';

const ob = new OpenBiometrics({
  apiKey: process.env.OB_API_KEY!,
  // baseUrl: 'http://localhost:8000', // for self-hosted
});

Face Detection

import { readFileSync } from 'fs';

const photo = readFileSync('photo.jpg');
const { faces, count } = await ob.faces.detect(photo);

for (const face of faces) {
  console.log(`Age: ${face.demographics?.age}`);
  console.log(`Gender: ${face.demographics?.gender}`);
  console.log(`Quality: ${face.quality?.overall_score}/100`);
  console.log(`Live: ${face.liveness?.is_live}`);
}

1:1 Verification

const id = readFileSync('id_card.jpg');
const selfie = readFileSync('selfie.jpg');

const { is_match, similarity } = await ob.faces.verify(id, selfie);

if (is_match) {
  console.log(`Identity verified (${(similarity * 100).toFixed(1)}% match)`);
}

Watchlist Operations

// Enroll
const result = await ob.watchlists.enroll(photo, { label: 'Alice' });
console.log(`Enrolled: ${result.identity_id}`);

// Identify
const { matches } = await ob.watchlists.identify(unknownPhoto);
const topMatch = matches[0];
if (topMatch) {
  console.log(`Best match: ${topMatch.label} (${(topMatch.similarity * 100).toFixed(1)}%)`);
}

// Remove
await ob.watchlists.remove(result.identity_id);

// List
const { watchlists } = await ob.watchlists.list();

Liveness

const { is_live, score } = await ob.liveness.check(selfieBuffer);
if (!is_live) {
  throw new Error('Spoofing detected');
}

With Express

import express from 'express';
import multer from 'multer';
import { OpenBiometrics } from 'openbiometrics';

const app = express();
const upload = multer();
const ob = new OpenBiometrics({ apiKey: process.env.OB_API_KEY! });

app.post('/verify-identity', upload.fields([
  { name: 'id_photo' },
  { name: 'selfie' },
]), async (req, res) => {
  const { is_match, similarity } = await ob.faces.verify(
    req.files['id_photo'][0].buffer,
    req.files['selfie'][0].buffer,
  );
  res.json({ verified: is_match, confidence: similarity });
});

Document Processing

Scan identity documents, extract text via OCR, and parse MRZ zones.

import { readFileSync } from 'fs';

const idCard = readFileSync('id_card.jpg');

// Full document scan (detect type + OCR + MRZ)
const doc = await ob.documents.scan(idCard);
console.log(`Type: ${doc.document_type}`);
console.log(`Surname: ${doc.mrz?.parsed.surname}`);

// OCR only
const ocr = await ob.documents.ocr(idCard);
console.log(ocr.text);

// MRZ only
const mrz = await ob.documents.mrz(idCard);
console.log(mrz.parsed);

// Verify a selfie against the document photo
const selfie = readFileSync('selfie.jpg');
const { is_match, similarity } = await ob.documents.verify(selfie, idCard);
console.log(`Document match: ${is_match} (${(similarity * 100).toFixed(1)}%)`);

Active Liveness

Interactive challenge-response liveness sessions for verifying a real person is present.

// Create a session with specific challenges
const session = await ob.liveness.createSession({
  challenges: ['blink', 'turn_left'],
  ttl_seconds: 120,
});
console.log(`Session: ${session.session_id}`);
console.log(`First challenge: ${session.challenges[0]}`);

// Submit frames as the user completes challenges
const frame = readFileSync('frame_001.jpg');
const updated = await ob.liveness.submitFrame(session.session_id, frame);
console.log(`Status: ${updated.status}`);

// Check session state
const state = await ob.liveness.getSession(session.session_id);
console.log(`Completed: ${state.status}`);

// Cancel a session
await ob.liveness.deleteSession(session.session_id);

Video Management

Manage RTSP camera sources for real-time face processing.

// Add a camera
const camera = await ob.video.addCamera({
  name: 'Lobby',
  url: 'rtsp://192.168.1.100/stream',
  fps: 5,
});
console.log(`Camera ID: ${camera.camera_id}`);

// List all cameras
const cameras = await ob.video.listCameras();
for (const cam of cameras) {
  console.log(`${cam.name}: ${cam.status}`);
}

// Get a snapshot
const snapshot = await ob.video.getSnapshot(camera.camera_id);

// Remove a camera
await ob.video.removeCamera(camera.camera_id);

Events & Webhooks

Subscribe to events and register webhooks for real-time notifications.

// Register a webhook
const webhook = await ob.events.registerWebhook({
  url: 'https://example.com/hooks/ob',
  events: ['face.identified', 'liveness.completed'],
});
console.log(`Webhook ID: ${webhook.webhook_id}`);
console.log(`Secret: ${webhook.secret}`);

// List webhooks
const webhooks = await ob.events.listWebhooks();

// Get recent events
const events = await ob.events.getRecent({ type: 'face.identified', limit: 10 });
for (const event of events) {
  console.log(`${event.type} at ${event.timestamp}`);
}

// Delete a webhook
await ob.events.deleteWebhook(webhook.webhook_id);

Admin

Health checks, model status, and runtime configuration.

// Health check
const health = await ob.admin.health();
console.log(`Status: ${health.status}, Uptime: ${health.uptime_seconds}s`);

// List loaded models
const models = await ob.admin.models();
for (const model of models) {
  console.log(`${model.name}: ${model.status}`);
}

// Get current config
const config = await ob.admin.config();
console.log(config);

// Update config
await ob.admin.config({ max_faces: 10, det_thresh: 0.6 });