faceapi-client 1.0.0

Official Python SDK for the FaceAPI — privacy-first face recognition

FaceAPI Python SDK

Official Python client for the FaceAPI — privacy-first face recognition.

Install

pip install faceapi-client

Or directly from GitHub:

pip install git+https://github.com/zeinvob/face-recognition-api.git#subdirectory=sdk

Quick Start

from faceapi import FaceAPIClient

client = FaceAPIClient(api_key="fk_live_your_key_here")

Get your free API key at: https://face-recognition-api-om7k.onrender.com/portal/

---

Enroll a Face

import face_recognition

# Extract descriptor from an image (client-side — no photo sent to API)
image      = face_recognition.load_image_file("photo.jpg")
descriptor = face_recognition.face_encodings(image)[0].tolist()

result = client.enroll(
    descriptor=descriptor,
    label="john_doe",           # optional
    collection_id="my_app",     # optional namespace
)

print(result.face_id)    # store this in your database
print(result.enrolled)   # True = new, False = updated existing

---

Verify a Face (1:1)

result = client.verify(
    descriptor=descriptor,   # freshly captured
    face_id="<stored_face_id>",
)

if result.verified:
    print(f"Identity confirmed! Confidence: {result.confidence:.0%}")
else:
    print("Face does not match")

---

Identify a Face (1:N — Who Is This?)

result = client.identify(
    descriptor=descriptor,
    collection_id="my_app",   # search only this namespace
)

if result.identified:
    print(f"Hello, {result.label}! Confidence: {result.confidence:.0%}")
else:
    print("Unknown person")

---

List Enrolled Faces

faces = client.list_faces(collection_id="my_app")
print(f"Total enrolled: {faces.count}")
for face in faces.faces:
    print(face.face_id, face.label, face.enrolled_at)

---

Delete a Face

client.delete_face(face_id="<face_id>")

---

GDPR Purge

# Delete all faces for one user (collection)
result = client.purge(collection_id="user_123")
print(f"Deleted {result.deleted_count} faces")

# Delete everything for your API key
result = client.purge()

---

Check Usage

stats = client.usage()
print(f"Tier: {stats.tier}")
print(f"Used today: {stats.used_today} / {stats.daily_limit or 'unlimited'}")
print(f"Total requests: {stats.total_requests}")

---

Error Handling

from faceapi import (
    FaceAPIClient,
    AuthenticationError,
    RateLimitError,
    NotFoundError,
)

try:
    result = client.verify(descriptor=descriptor, face_id=face_id)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited: {e}")
except NotFoundError:
    print("face_id not found")

---

Full Attendance System Example

import face_recognition
from faceapi import FaceAPIClient

client = FaceAPIClient(api_key="fk_live_your_key_here")

def enroll_employee(photo_path: str, employee_id: str) -> str:
    image      = face_recognition.load_image_file(photo_path)
    descriptor = face_recognition.face_encodings(image)[0].tolist()
    result     = client.enroll(descriptor=descriptor, label=employee_id, collection_id="employees")
    return result.face_id

def clock_in(photo_path: str):
    image      = face_recognition.load_image_file(photo_path)
    descriptor = face_recognition.face_encodings(image)[0].tolist()
    result     = client.identify(descriptor=descriptor, collection_id="employees")

    if result.identified:
        print(f"Welcome, {result.label}! Clocked in. (confidence: {result.confidence:.0%})")
    else:
        print("Face not recognized. Access denied.")

# Enroll once
enroll_employee("john.jpg", "EMP001")

# Identify on every clock-in
clock_in("camera_frame.jpg")