Linux

Faceplugin ID Document Liveness Linux SDK. On-premise document anti-spoofing HTTP API. Docker image faceplugin/document-liveness, POST /api/documentLiveness on port 8086.

Code

GitHub - Faceplugin-ltd/ID-Document-Liveness-Detection-Docker: ID Document Liveness Detection SDK for Linux & Docker — on-premise document anti-spoofing for ID cards, passports, and driver licenses.GitHub

Setup

Sizing: Hosting requirements.

Pull and run the Docker Hub image:

sudo docker pull faceplugin/document-liveness:latest
sudo 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

--shm-size=2gb is required.

Health (no license): curl -s http://127.0.0.1:8086/api/health
Get machine code: GET /api/machinecode
Contact us for license key, then POST /api/activate

Run multiple containers with one license

You only need this section if you want to run multiple Document Liveness containers on the same Linux host.

On Linux, mount /etc/machine-id into each container so they use the same machine code. Each container must have a different container name and host port.

For example:

sudo 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 container with the same license key (POST /api/activate on each host port).

On Docker Desktop (macOS/Windows), omit the /etc/machine-id volume. Each container may require its own license.

Other ways to run

Option B — Docker Compose (local build)

git clone https://github.com/Faceplugin-ltd/ID-Document-Liveness-Detection-Docker.git
cd ID-Document-Liveness-Detection-Docker

Put the Google Drive runtime files directly in lib/cpu/, then:

# 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 -f

Option C — Native Linux (no Docker)

Same lib/cpu/ layout:

./run.sh

On Docker Desktop omit the /etc/machine-id volume for Hub and Compose runs.

Default port 8086. Gradio demo on 9006 (host only).

Need OCR as well? Use ID Document Recognition Linux SDK.

APIs

Endpoint

Purpose

GET /api/health

Process is listening (no license)

GET /api/machinecode

Machine code

GET /api/licenseStatus

License status

GET /api/backend

"cpu"

POST /api/activate

Activate and init_sdk()

POST /api/documentLiveness

Authenticity / document anti-spoofing

Full reference: Document Liveness HTTP API. Shared control routes: Shared endpoints.

Some routes wrap the result in a small JSON object (an envelope). POST /api/documentLiveness returns engine JSON as the body. There is no documentRecognition / documentProcess on this product.

Python:

import sdk

sdk.activate("license.txt")
sdk.init_sdk()
print(sdk.document_liveness([{"image": base64_front}, {"image": base64_back, "page_idx": 1}]))

Try it

curl -s http://127.0.0.1:8086/api/health
IMG=$(base64 -w0 id-front.jpg)

curl -s -X POST http://127.0.0.1:8086/api/documentLiveness \
  -H 'Content-Type: application/json' \
  -d "{\"images\":[{\"image\":\"$IMG\",\"page_idx\":0}]}"

Postman: import postman/DocumentLiveness-API.postman_collection.json from the repo. Base URL http://127.0.0.1:8086.

Gradio (host only): port 9006. There is no documentRecognition / documentProcess on this product — authenticity only. Security keys: Document security check fields.

Request a License & Support · Contact us

FAQ

Document anti-spoofing API? POST /api/documentLiveness on port 8086. No OCR.

Need passport OCR too? Use ID Document Recognition Linux with a Liveness-capable license, or run both containers and call each API from your backend.