faceplugin/document-liveness repository overview

⁠FacePlugin ID Document Liveness Detection

On-premise document authenticity / security (presentation-attack) checks HTTP API. Linux amd64. Official image: faceplugin/document-liveness⁠.

The image is an API/SDK server only (no Gradio). Runtime libraries are already inside — no Google Drive download is required to pull and run. This version is CPU-only.

Detects screen replay, printed copies, portrait substitution, and related authenticity checks on ID cards, passports, and driver licenses. This is document liveness — not face PAD (faceplugin/face-liveness).

• Company: faceplugin.com⁠
• Docs: doc.faceplugin.com⁠
• GitHub: Faceplugin-ltd/ID-Document-Liveness-Detection-Docker⁠
• Contact: [email protected]⁠ · WhatsApp +1 469 278 4822⁠

⁠Tags

docker pull faceplugin/document-liveness:latest

⁠Quick start

Default listen port 8086. Use --shm-size=2gb (the SDK unpacks models into /dev/shm; Docker’s 64MB default is too small).

docker run -d --name faceplugin-document-liveness \
  --shm-size=2gb --privileged \
  -p 8086:8086 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/document-liveness:latest

docker logs -f faceplugin-document-liveness
# Look for the machine code line: FPMC1.…

API: http://127.0.0.1:8086

macOS / Windows Docker Desktop: omit -v /etc/machine-id:/etc/machine-id:ro (there is no host /etc/machine-id). Each container may get a different machine code.

⁠License

The published image does not include a license. The API starts without one and prints a machine code (FPMC1.…). Product endpoints unlock after you activate.

1. Copy the machine code from logs, or GET /api/machinecode.
2. Send that code to FacePlugin. You receive a license key (FP1.…).
3. Activate:

# Paste the FP1. key into license.txt, then:
curl -s -X POST http://127.0.0.1:8086/api/activate \
  -H 'Content-Type: text/plain' \
  --data-binary @license.txt

Docker and native-host codes are different. If you run in Docker, send the Docker machine code.

Use a license that includes Liveness (authenticity). This product does not expose OCR / MRZ / Barcode.

⁠Several containers, one license

On Linux, keep the machine-id mount so extra containers on the same host share one fingerprint. Use a new name and host port:

docker run -d --name faceplugin-document-liveness-2 \
  --shm-size=2gb --privileged \
  -p 8087:8086 \
  -v /etc/machine-id:/etc/machine-id:ro \
  faceplugin/document-liveness:latest

Activate each published port with the same key. Without the machine-id volume (typical Docker Desktop), codes can differ.

⁠API (after activation)

Health:

curl -s http://127.0.0.1:8086/api/health

Example request:

curl -s -X POST http://127.0.0.1:8086/api/documentLiveness \
  -H 'Content-Type: application/json' \
  -d '{"images":[{"image":"<BASE64>"}]}'

Postman collection, Gradio demo (runs on the host, not in this image), and native setup: ID-Document-Liveness-Detection-Docker⁠.