Skip to content

About

On-premises face liveness detection & anti-spoofing REST API (Python/FastAPI). Passive PAD/liveness + 1:1 face matching with the FaceOnLive biometric SDK.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Face Liveness Detection API (Python / FastAPI)

CI

License: MIT Python FastAPI

A production-shaped REST API for face liveness detection and 1:1 face matching, powered by the FaceOnLive biometric SDK. It performs passive anti-spoofing / presentation attack detection (PAD) (aligned with ISO/IEC 30107) to tell a live person apart from print, screen-replay, and mask attacks, plus 1:1 face comparison — all running on-premises / on-device with no per-call cloud fees. This example shows how to wrap the native SDK behind a clean FastAPI service.

This repository is part of the FaceOnLive on-premises biometric SDK suite. It is honest, MIT-licensed example integration code that calls the proprietary FaceOnLive engine. Learn more at faceonlive.com and on the FaceOnLive GitHub org.

Features

  • Passive face liveness / anti-spoofing (PAD) — single-image, no user action required.
  • 1:1 face match — extract templates from two images and compare them.
  • On-premises — the engine is a native shared library; images never leave your infrastructure.
  • Clean integration seam — a single, clearly-marked ctypes wrapper (app/faceonlive.py) is the only place that touches the native SDK.
  • Robust I/O — multipart upload handling with Pillow-based image validation and proper 400 / 413 / 422 / 500 / 503 error responses.
  • Container-ready — Dockerfile included; mount your licensed .so at runtime.

Requirements

  • Python 3.11+
  • The FaceOnLive native SDK shared library for your platform (.so / .dll / .dylib) and a license key — free trial at faceonlive.com.
  • Dependencies in requirements.txt (FastAPI, Uvicorn, Pydantic, python-multipart, Pillow, NumPy).

Quickstart

  1. Get a free license key and download the SDK build for your platform at faceonlive.com.

  2. Configure environment. Copy the example and edit it:

    cp .env.example .env

    Set at least:

    FACEONLIVE_LICENSE_KEY=<YOUR_LICENSE_KEY>
    FACEONLIVE_SDK_LIB=/opt/faceonlive/libfaceonlive.so
  3. Install dependencies:

    pip install -r requirements.txt
  4. Load the environment and run:

    set -a && . ./.env && set +a          # export the vars from .env
    uvicorn app.main:app --host 0.0.0.0 --port 8000

    Open the interactive docs at http://localhost:8000/docs.

API Reference

Method Path Description
GET /health Health/readiness probe; reports whether the SDK is activated.
POST /v1/liveness Passive liveness / PAD on one uploaded image.
POST /v1/face/match 1:1 comparison of two uploaded face images.

POST /v1/liveness returns:

{ "is_live": true, "liveness_score": 0.982, "faces": 1, "threshold": 0.5 }

POST /v1/face/match returns:

{ "similarity": 0.874, "is_match": true, "threshold": 0.7 }

Example request

Liveness check on a single image:

curl -X POST http://localhost:8000/v1/liveness \
  -F "image=@/path/to/selfie.jpg"

1:1 face match with two images:

curl -X POST http://localhost:8000/v1/face/match \
  -F "image1=@/path/to/id_photo.jpg" \
  -F "image2=@/path/to/selfie.jpg"

How the SDK integration works

The FaceOnLive engine ships as a native shared library (.so on Linux). All native calls are isolated in one file — app/faceonlive.py — which loads the library via Python's ctypes and exposes a small, Pythonic surface:

  • activate(license_key) -> int — one-time license activation (0 = success)
  • init() -> int — load models / initialize the engine
  • detect_faces(image_bytes) -> list — face bounding boxes
  • liveness(image_bytes) -> float — passive PAD score in [0, 1]
  • extract_template(image_bytes) -> bytes — face recognition template
  • compare(t1, t2) -> float — template similarity in [0, 1]

FastAPI startup (lifespan in app/main.py) activates and initializes the SDK once per process, then reuses that handle for every request.

The exact exported C symbol names and their signatures depend on your licensed SDK build. Every point you must adapt is marked with a # >>> BIND: comment in app/faceonlive.py — update the argtypes / restype / call sites to match the header shipped with your SDK (use nm -D libfaceonlive.so to list the exported symbols). See the FaceOnLive docs for authoritative prototypes.

If the shared library or license key is missing or invalid, the wrapper raises a clear RuntimeError and biometric endpoints return 503 — the service never fabricates biometric results.

Docker

Build the image:

docker build -t face-liveness-detection-api .

Run it, mounting your licensed SDK and passing the license key (the proprietary .so is intentionally not baked into the image):

docker run --rm -p 8000:8000 \
  -e FACEONLIVE_LICENSE_KEY=<YOUR_LICENSE_KEY> \
  -e FACEONLIVE_SDK_LIB=/opt/faceonlive/libfaceonlive.so \
  -v /opt/faceonlive:/opt/faceonlive:ro \
  face-liveness-detection-api

License & links

About

On-premises face liveness detection & anti-spoofing REST API (Python/FastAPI). Passive PAD/liveness + 1:1 face matching with the FaceOnLive biometric SDK.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages