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.
- 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
ctypeswrapper (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 / 503error responses. - Container-ready — Dockerfile included; mount your licensed
.soat runtime.
- 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).
-
Get a free license key and download the SDK build for your platform at faceonlive.com.
-
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
-
Install dependencies:
pip install -r requirements.txt
-
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.
| 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 }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"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 enginedetect_faces(image_bytes) -> list— face bounding boxesliveness(image_bytes) -> float— passive PAD score in[0, 1]extract_template(image_bytes) -> bytes— face recognition templatecompare(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.
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- Example code: MIT. The FaceOnLive SDK itself is proprietary and licensed separately.
- Website: https://faceonlive.com
- Documentation: https://faceonlive.com/docs/
- Face Recognition & Liveness SDK: https://github.com/FaceOnLive/Face-Recognition-SDK-Android and the FaceOnLive GitHub org
- Contact: contact@faceonlive.com