🌐 Company Site - Here
🤗 Hugging Face - Here
🛟 Help Center - Here
🐳 Docker Hub - Here
Ready in minutes:
docker pull→ copyFPMC1.…from logs →curl /api/health.
Jump: Quick Start · Start the API · SDK License · Setup on your own app · Try it
- Download and run the appropriate Docker image from FacePlugin Docker Hub. See Option A for details.
- Confirm it is running:
curl -s http://127.0.0.1:8084/api/health(no license needed yet) - Contact us with your machine code (
FPMC1.…) to obtain a license key, then activate withPOST /api/activate— SDK License - Try it: Postman, curl, or local Gradio demo on 9004 (
demo.py)
Docs: https://doc.faceplugin.com
FacePlugin Face Liveness SDK for Linux / Docker is a fully on-premise anti-spoofing engine for KYC and remote identity verification. It scores a single RGB face image for presentation attacks — printed photos, screens, printouts, and video replay — and returns Real / Spoof with a pass score.
This repository is standalone. Pull Docker Hub (no Drive) or download the runtime into this repo and run — no other FacePlugin repository is required.
All processing stays on your server. No biometric data is sent to FacePlugin cloud — built for banking, eKYC, and on-premise compliance workflows.
One repository for Linux SDK + Docker. Native libraries are linux/amd64. The Docker image runs on Linux, Windows, and macOS hosts (Apple Silicon uses amd64 emulation). This product is CPU-only.
Test with curl, Postman, or the local Gradio demo (demo.py). Docs: https://doc.faceplugin.com.
| Feature | API |
|---|---|
| RGB face liveness (all engines combined) | POST /api/liveness · sdk.liveness |
| Photo, screen, print, and replay presentation-attack detection | same call |
| Score, Real/Spoof, pass | data.score · data.result · data.pass |
| Health / machine code / activate | GET /api/health · GET /api/machinecode · POST /api/activate |
| License capabilities | GET /api/licenseStatus · sdk.get_license_status |
Score ≥ 0.5 → result: "Real", pass: true. Score < 0.5 → result: "Spoof", pass: false.
POST /api/check_liveness is an alias of /api/liveness.
| Platform | Repository |
|---|---|
| Android (Recognition) | FaceRecognition-Android |
| iOS (Recognition) | FaceRecognition-iOS |
| React Native (Recognition) | FaceRecognition-React-Native |
| Flutter (Recognition) | FaceRecognition-Flutter |
| Ionic Capacitor (Recognition) | FaceRecognition-Ionic-Capacitor |
| Ionic Cordova (Recognition) | FaceRecognition-Ionic-Cordova |
| Windows (Recognition) | FaceRecognition-Windows |
| Linux / Docker (Recognition) | FaceRecognition-Docker |
| Android (Liveness) | FaceLivenessDetection-Android |
| iOS (Liveness) | FaceLivenessDetection-iOS |
| Windows (Liveness) | FaceLivenessDetection-Windows |
| Linux / Docker (Liveness) | FaceLivenessDetection-Docker (this repo) |
| Step | What you need |
|---|---|
| 1 | A Linux host or Docker |
| 2 | Docker Hub pull does not require Google Drive. Populate ./lib/cpu/ only for Compose or ./run.sh — see Get the runtime |
| 3 | Start without a license. Copy FPMC1.… from logs or GET /api/machinecode, send it to FacePlugin (contact), then activate with your license key |
| Item | Minimum | Recommended |
|---|---|---|
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Disk | 4 GB | 8 GB |
| OS (Docker) | Linux + Docker Engine | Ubuntu 22.04 / 24.04 |
OS (local ./run.sh) |
Ubuntu 20.04+ (x86_64), Python 3.10+ | Ubuntu 22.04 / 24.04 |
You can start without a license — the server prints your machine code on startup.
The API starts even if activation fails. Copy the machine code (FPMC1.…) from the log and send it to FacePlugin.
sudo docker pull faceplugin/face-liveness:latest
sudo docker run -d --name faceplugin-face-liveness \
--shm-size=1gb --privileged \
-p 8084:8084 \
-v /etc/machine-id:/etc/machine-id:ro \
faceplugin/face-liveness:latest
sudo docker logs -f faceplugin-face-liveness
# Look for the machine code line: FPMC1.…On Linux, add -v /etc/machine-id:/etc/machine-id:ro to the docker run above so the machine code stays on that host. Then start another container with a new name and host port — same image, same license key:
sudo docker run -d --name faceplugin-face-liveness-2 \
-p 8085:8084 \
-v /etc/machine-id:/etc/machine-id:ro \
faceplugin/face-liveness:latestActivate on each host port with the same key. On Docker Desktop (macOS/Windows) skip the machine-id volume; each container may need its own license.
Skip this if you used Docker Hub (docker pull / docker run). Runtime is already inside the image.
./lib/cpu/ is empty on GitHub because binaries are too large. Face Liveness Linux is CPU-only — there is no gpu/ package.
FaceLiveness-Linux runtime (Google Drive)
- Clone the repo:
git clone https://github.com/Faceplugin-ltd/FaceLivenessDetection-Docker.git
cd FaceLivenessDetection-Docker- Download all files from the Drive folder.
- Put every file directly into
./lib/cpu/— not inside a nested subfolder.
FaceLivenessDetection-Docker/
└── lib/
└── cpu/
├── libFaceLivenessSDK.so
├── libfal-eng.so
├── fal.fpk
└── …
ls lib/cpu/libFaceLivenessSDK.so
ls lib/cpu/fal.fpkIf those paths exist, you are ready for Option B or C.
Requires ./lib/cpu/ filled from Drive.
cd FaceLivenessDetection-Docker
# macOS/Windows Docker Desktop: remove the /etc/machine-id volume from docker-compose.yml first
sudo docker compose up --build -d
sudo docker compose logs -fDetached Compose has no TTY — activate with curl (below).
Requires ./lib/cpu/ filled from Drive.
cd FaceLivenessDetection-Docker
pip3 install -r requirements.txt
./run.shLicenses are offline and bound to a machine code. Offline cryptography is built into the SDK — no OpenSSL install.
- Start the server (above). A license is not required for the first start.
- Copy the machine code from the log (
FPMC1.…). - Send that code to FacePlugin (contact). We issue a license key for that code.
- Activate with the license key:
# Paste your license key into ./license.txt, then:
curl -s -X POST http://127.0.0.1:8084/api/activate \
-H 'Content-Type: text/plain' \
--data-binary @license.txt
Or stop the process, save license.txt, and run ./run.sh / docker compose restart again.
Docker and local host codes are different. Use the machine code from the environment you will run in production.
After activation, GET /api/licenseStatus reports what the key unlocks. The Gradio demo shows the same summary as License: at the top of the page.
This App exposes liveness APIs only. Typical labels:
- Liveness only / Recognition + Liveness —
/api/liveness - Recognition only — liveness stays unavailable on this App
- Not licensed — machine code only until you activate
curl -s http://127.0.0.1:8084/api/licenseStatuscurl -s http://127.0.0.1:8084/api/healthcurl -s -X POST http://127.0.0.1:8084/api/liveness \
-H 'Content-Type: application/json' \
-d '{"image":"<base64-jpeg>"}'Success data:
{ "score": 0.72, "result": "Real", "pass": true }Docs: https://doc.faceplugin.com
Import postman/FaceLiveness-API.postman_collection.json. Base URL: http://127.0.0.1:8084
The Docker image is API-only (no Gradio). For a local FacePlugin Face Liveness demo in the browser — Real / Spoof score and Pass — with the API already running on port 8084. The header shows License: from /api/licenseStatus.
pip3 install -r requirements-demo.txt
DEMO_PORT=9004 API_BASE=http://127.0.0.1:8084 python3 demo.pyOpen http://127.0.0.1:9004. Samples: assets/examples/samples/.
Each run shows Score, Result (Real or Spoof), and Pass for presentation-attack detection.
Two ways to call the same engine. Full protocol: https://doc.faceplugin.com.
| Path | When to use |
|---|---|
HTTP (app.py) |
Any language. Keep this API running and POST a base64 JPEG. |
sdk.py |
Python on the same Linux host as lib/cpu/ (or inside the container). No HTTP hop. |
HTTP (any language): start the API, then POST /api/liveness with {"image":"<base64-jpeg>"}. See Try it and Postman.
Python in-process: copy sdk.py + lib/cpu/ into your project (or import sdk from this repo). Call order: get_machine_code → activate → init_sdk → liveness. Check get_license_status() for the liveness flag. Return code 0 means success.
You do not need Gradio (demo.py) in production — it is a host-only test UI.
Python bindings: sdk.py. Return code 0 means success.
import sdk
machine_code = sdk.get_machine_code() # FPMC1.…
sdk.activate("license.txt")
sdk.init_sdk()
result = sdk.liveness(base64_image)result is JSON. data is { "score": <float>, "result": "Real" | "Spoof", "pass": <bool> }. All RGB engines are always run and combined.
