# Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://doc.faceplugin.com/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Welcome Faceplugin on-premise Face Recognition, Liveness, and ID Document Recognition SDK docs. Offline Android, iOS, Flutter, React Native, Windows, and Linux Docker integration guides. ### Introduction **Faceplugin** builds **on-premise, offline** biometric SDKs. Processing stays on the phone, your Windows/Linux host, or your Docker host. There is no per-call Faceplugin cloud. ### What you can build * **Passport OCR & ID verification** — classify and read **16,900** document templates from **255** countries (MRZ — the machine-readable zone on passports — plus barcode and optional authenticity). Start: [ID Document capabilities](/products/id-document-recognition-sdk/capabilities) · [Passport OCR guide](/help/resources/passport-ocr-and-id-verification) * **Face recognition & liveness** — offline 1:1 match, mobile 1:N Identify, standalone face anti-spoofing, or recognition + liveness in one server process. Start: [Face SDK capabilities](/products/face-recognition-sdk/capabilities) Product hubs: [Face SDK](/products/face-recognition-sdk) · [ID Document SDK](/products/id-document-recognition-sdk) · [Palm Recognition](/products/palm-recognition-sdk) This documentation is the **integration** layer: clone a public GitHub sample, add the Google Drive runtime package or pull Docker Hub, activate a license, then call the APIs that repository actually exposes. ### How to use these docs 1. Read **Capabilities** for the product you need (what it can do). 2. Open **Mobile SDK** or **Server SDK**, then the **platform** page (Android, iOS, Flutter, React Native, Linux, Windows, …). 3. Follow **Setup** / **How to run** to place the Google Drive runtime package and start the **GitHub sample app** for that product. 4. Copy the **machine code** if you run a server SDK, then [request a license](/help/request-a-license-and-support). 5. Use [Try it](/getting-started/try-it) and the [HTTP API](/integration/http-api) to call the same server APIs from your app. Store templates and document JSON in **your** database. Ports: Document **8082**, Face Recognition **8083**, Face Liveness **8084**, Document Liveness **8086**. For topology and sizing, see [Deploy and host](/integration/deploy-and-host). Native binaries are **not** on GitHub (too large). Each platform page links the Google Drive folder and the exact copy path. {% hint style="info" %} Each GitHub sample app is a complete application for testing. In production, use the runtime directly: copy the runtime, call `activate` → `init`, then call the processing APIs. {% endhint %} ### Our Products
Cover image
Face SDKRecognition, liveness, and recognition + liveness — mobile and serverhttps://raw.githubusercontent.com/Faceplugin-ltd/faceplugin-assets/main/screenshots/face-recognition/android/identify.pngFace SDK
ID Document SDKPassport OCR, authenticity-only liveness, and OCR + authenticity — 16,900 templateshttps://raw.githubusercontent.com/Faceplugin-ltd/faceplugin-assets/main/screenshots/document-reader/mobile/camera.pngID Document SDK
Palm Recognition SDKOpen-source RGB-camera palm matching samplehttps://raw.githubusercontent.com/Faceplugin-ltd/faceplugin-assets/main/screenshots/face-recognition/android/identify.pngPalm Recognition SDK
### Try our SDKs * [GitHub repos](https://github.com/Faceplugin-ltd) * [Playground](https://playground.faceplugin.com/) * [Hugging Face Spaces](https://huggingface.co/Faceplugin-Ltd) * [Docker Hub](https://hub.docker.com/u/faceplugin) * [Try it (copy-paste)](/getting-started/try-it) ### Features * Offline after license activation — no Faceplugin cloud inference * HTTP APIs on ports **8082** (documents), **8083** (face recognition), **8084** (face liveness), **8086** (document liveness) * Mobile SDKs for Android, iOS, Flutter, React Native, and Ionic (platform support varies by product) ### Platforms Platforms vary by product. **Face Recognition** and **ID Document Recognition** include Android, iOS, Flutter, React Native, Ionic, Windows, and Linux/Docker. **Face Liveness** is Android, iOS, Windows, and Linux/Docker (no public Flutter or React Native SDK). ### Use cases * **eKYC / digital onboarding** — ID OCR + optional authenticity + selfie liveness + face match ([Architecture](/integration/deploy-and-host/architecture)) * **Banking and fintech** — passport / ID verification and face anti-spoofing on your infrastructure * **Access control and attendance** — mobile 1:N Identify with templates you store * **Fraud prevention** — reject presentation attacks and document spoofs before enrollment ### Related documentation * [Choose a product](/getting-started/choose-a-product) · [Try it](/getting-started/try-it) · [HTTP API](/integration/http-api) · [Deploy and host](/integration/deploy-and-host) * [Glossary](/help/resources/glossary) · [FAQ](/help/resources/faq) * [Request a License & Support](/help/request-a-license-and-support) · [SDK comparison](/help/comparisons) * [Status codes](/help/resources/status-codes) · [Troubleshooting](/help/resources/troubleshooting) · [Changelog](/help/resources/changelog) # Choose a product Choose a Faceplugin product and platform. Public GitHub repos, Docker images, ports, and how to combine Face Recognition, Liveness, and ID Document SDKs in an eKYC flow. Use this page as a catalog: **which GitHub repository to clone**, what the package or Docker image is called, and which HTTP port each server product listens on. Always clone the **public** GitHub repository name shown in the tables below (for example `ID-Document-Recognition-Android`). Need a vendor comparison? See [SDK comparison](/help/comparisons). ## Which product? | You need | Use | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Passport OCR / MRZ / ID card verification | [ID Document capabilities](/products/id-document-recognition-sdk/capabilities) → [ID Document SDK](/products/id-document-recognition-sdk) · [Recognition](/products/id-document-recognition-sdk/recognition) | | Match faces 1:1 or 1:N / Face Recognition API | [Face SDK capabilities](/products/face-recognition-sdk/capabilities) → [Face SDK](/products/face-recognition-sdk) · [Recognition](/products/face-recognition-sdk/recognition) | | Face anti-spoofing only | [Face SDK capabilities](/products/face-recognition-sdk/capabilities) → [Liveness](/products/face-recognition-sdk/liveness-detection-sdk) | | Recognition and anti-spoofing together | For recognition plus liveness on one server, use [Face Recognition + Liveness Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) or [Windows](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-windows) (port **8083**, includes `/api/liveness`). Or run separate services on **8083** and **8084**—never mix their runtime folders. | | Document authenticity **without** OCR | [ID Document Liveness SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk) | ## ID Document Recognition Scan passports, national IDs, and driver licenses on the device or over HTTP (**16,900** templates, **255** countries). Document authenticity (anti-spoofing of the ID itself) needs a license that includes that feature, unless you use the dedicated Document Liveness Linux product (authenticity only). Overview: [Document capabilities](/products/id-document-recognition-sdk/capabilities). | Platform | Clone | Package / image | Port | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------- | | Android | [ID-Document-Recognition-Android](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Android) | `documentreadersdk.aar` | — | | iOS | [ID-Document-Recognition-iOS](https://github.com/Faceplugin-ltd/ID-Document-Recognition-iOS) | `docsdk.framework` | — | | Flutter | [ID-Document-Recognition-Flutter](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Flutter) | `document_reader_sdk` | — | | React Native | [ID-Document-Recognition-React-Native](https://github.com/Faceplugin-ltd/ID-Document-Recognition-React-Native) | `document-reader-sdk` | — | | Ionic Capacitor | [ID-Document-Recognition-Ionic-Capacitor](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Ionic-Capacitor) | `document-reader-capacitor` | — | | Ionic Cordova | [ID-Document-Recognition-Ionic-Cordova](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Ionic-Cordova) | Cordova plugin | — | | Windows | [ID-Document-Recognition-Windows](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Windows) | `sdk.py` + `app.py` | API **8082**, demo **9002** | | Linux / Docker | [ID-Document-Recognition-Docker](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Docker) | `faceplugin/document-reader` | API **8082**, demo **9002** | | Node.js HTTP | [ID-Document-Recognition-Node](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Node) | HTTP API (optional native lib) | API **8082** | | Go / C++ HTTP | [ID-Document-Recognition-Go](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Go), […-CPP](https://github.com/Faceplugin-ltd/ID-Document-Recognition-CPP) | HTTP API | API **8082** | | JavaScript client | [ID-Document-Recognition-JavaScript](https://github.com/Faceplugin-ltd/ID-Document-Recognition-JavaScript) | Browser + Node client | → **8082** | | React / Vue / Angular | […-React](https://github.com/Faceplugin-ltd/ID-Document-Recognition-React), […-Vue](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Vue), […-Angular](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Angular) | Web demos (HTTP) | → **8082** | ## Face Recognition Detect faces, read attributes, extract templates, and match 1:1. Mobile demos also support live **1:N Identify** (VideoWorker) and a local person database. Server APIs currently expose still-image detect / quality / feature / match / similarity — not a gallery-based 1:N identification endpoint. Capability overview: [Face SDK capabilities](/products/face-recognition-sdk/capabilities). | Platform | Clone | Package / image | Port | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------- | | Android | [FaceRecognition-Android](https://github.com/Faceplugin-ltd/FaceRecognition-Android) | `facerecognitionsdk.aar` | — | | iOS | [FaceRecognition-iOS](https://github.com/Faceplugin-ltd/FaceRecognition-iOS) | `facerecognitionsdk` + engine + onnxruntime | — | | Flutter | [FaceRecognition-Flutter](https://github.com/Faceplugin-ltd/FaceRecognition-Flutter) | `face_recognition_sdk` | — | | React Native | [FaceRecognition-React-Native](https://github.com/Faceplugin-ltd/FaceRecognition-React-Native) | `face-recognition-sdk` | — | | Ionic Capacitor | [FaceRecognition-Ionic-Capacitor](https://github.com/Faceplugin-ltd/FaceRecognition-Ionic-Capacitor) | `face-recognition-capacitor` | — | | Ionic Cordova | [FaceRecognition-Ionic-Cordova](https://github.com/Faceplugin-ltd/FaceRecognition-Ionic-Cordova) | Cordova plugin | — | | Windows (recognition) | [FaceRecognition-Windows](https://github.com/Faceplugin-ltd/FaceRecognition-Windows) | `sdk.py` + `app.py` | API **8083**, demo **9003** | | Linux / Docker (recognition) | [FaceRecognition-Docker](https://github.com/Faceplugin-ltd/FaceRecognition-Docker) | `faceplugin/face-recognition` | API **8083**, demo **9003** | | Windows (recognition + liveness) | [FaceRecognitionSDK-Windows](https://github.com/Faceplugin-ltd/FaceRecognitionSDK-Windows) | `sdk.py` + `app.py` | API **8083** (+ `/api/liveness`), demo **9003** | | Linux / Docker (recognition + liveness) | [FaceRecognition-LivenessDetection-Docker](https://github.com/Faceplugin-ltd/FaceRecognition-LivenessDetection-Docker) | `faceplugin/face-recognition-liveness-sdk` | API **8083** (+ `/api/liveness`), demo **9003** | ## Face Liveness Standalone presentation-attack detection (anti-spoofing). Mobile uses a live camera plus VideoWorker. The server scores a single RGB JPEG. Capability overview: [Face SDK capabilities](/products/face-recognition-sdk/capabilities) (Liveness section). | Platform | Clone | Package / image | Port | | -------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- | --------------------------- | | Android | [FaceLivenessDetection-Android](https://github.com/Faceplugin-ltd/FaceLivenessDetection-Android) | `facelivenessdk.aar` | — | | iOS | [FaceLivenessDetection-iOS](https://github.com/Faceplugin-ltd/FaceLivenessDetection-iOS) | `facelivenessdk` + engine + onnxruntime | — | | Windows | [FaceLivenessDetection-Windows](https://github.com/Faceplugin-ltd/FaceLivenessDetection-Windows) | `sdk.py` + `app.py` | API **8084**, demo **9004** | | Linux / Docker | [FaceLivenessDetection-Docker](https://github.com/Faceplugin-ltd/FaceLivenessDetection-Docker) | `faceplugin/face-liveness` | API **8084**, demo **9004** | {% hint style="info" %} Face Recognition mobile apps already include **2D liveness on Identify**. Use the standalone Face Liveness product when you need anti-spoofing without enrollment / 1:N. {% endhint %} ## ID Document Liveness Authenticity / anti-spoofing **only** (no OCR, MRZ, or barcode API). For OCR plus authenticity on one engine, use Document Reader with a Liveness-capable license. | Platform | Clone | Image | Port | | -------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------- | | Linux / Docker | [ID-Document-Liveness-Detection-Docker](https://github.com/Faceplugin-ltd/ID-Document-Liveness-Detection-Docker) | `faceplugin/document-liveness` | API **8086**, demo **9006** | ## Combining products (eKYC) **eKYC** means electronic know-your-customer / digital identity onboarding. Faceplugin does **not** offer one all-in-one identity-verification app. You combine Document Reader, Face Liveness, and Face Recognition in **your** mobile app or backend. Run **one process or container per product** (for eKYC: Document on **8082** and Face Recognition + Liveness on **8083**). Do not dump a second product’s Google Drive runtime into another product’s `lib/cpu/` — use two servers instead. Full topology, responsibility split, and HTTP vs `sdk.py`: [Architecture](/integration/deploy-and-host/architecture). Sizing and Docker flags: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). ### Related documentation * [Try it](/getting-started/try-it) · [HTTP API](/integration/http-api) · [Deploy and host](/integration/deploy-and-host) * [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) · [Troubleshooting](/help/resources/troubleshooting) * [Request a License](/help/request-a-license-and-support) # Try it Try Faceplugin SDKs with copy-paste commands. Start with license-free curl health and machine-code checks, then activate the SDK and test face detection, face matching, liveness, and document OCR. These snippets are meant to be **copied as-is**. You do not write a UI first. Start with `health` and `machinecode` (no license needed), then activate and call one process API. Full endpoint contracts: [HTTP API](/integration/http-api). {% hint style="info" %} **Start with the server if you want the quickest test.** Docker Hub + `curl` lets you test the SDK without Android Studio. Mobile snippets assume you have already run the demo once, with the required AAR/framework files in place and the demo license configured for the demo app ID. {% endhint %} ## 1. Server — no license yet Start any Linux/Windows server product, then: ```bash curl -s http://127.0.0.1:8083/api/health curl -s http://127.0.0.1:8083/api/machinecode ``` Change the port: **ID Document Recognition** (Document Reader) **8082**, Face Recognition **8083**, Face Liveness **8084**, Document Liveness **8086**. `health` works **before** you have a key. Copy the server **machine code** (machine code) from `machinecode` and [request a license](/help/request-a-license-and-support). ## 2. Server — activate once ```bash # license.txt contains one line: license key curl -s -X POST http://127.0.0.1:8083/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` Success looks like `"Successfully activated"`. The service also loads the engine on this call. ## 3. Server — try the main APIs for each product {% tabs %} {% tab title="Face Recognition" %} ```bash IMG=$(base64 -w0 face.jpg) # macOS: base64 -i face.jpg curl -s -X POST http://127.0.0.1:8083/api/detect \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" curl -s -X POST http://127.0.0.1:8083/api/match \ -H 'Content-Type: application/json' \ -d "{\"image1\":\"$IMG\",\"image2\":\"$IMG\"}" ``` Install: [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk). Combined recognition + liveness in one package: [Face Recognition + Liveness Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) (same port, adds `/api/liveness`). {% endtab %} {% tab title="Face Liveness" %} ```bash IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` Score **≥ 0.5** is Real / pass. JPEG only. [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk). Combined package on **8083**: same body against `/api/liveness` on [Recognition + Liveness Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux). {% endtab %} {% tab title="ID Document" %} ```bash FRONT=$(base64 -w0 passport_front.jpg) curl -s -X POST http://127.0.0.1:8082/api/documentRecognition \ -H 'Content-Type: application/json' \ -d "{\"images\":[{\"image\":\"$FRONT\",\"page_idx\":0}]}" ``` Combined pipeline: `POST /api/documentProcess`. Dedicated Document Liveness product: port **8086**. [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk). {% endtab %} {% endtabs %} Windows: use Git Bash or WSL for `base64`, or Python: ```python import base64, json, urllib.request img = base64.b64encode(open("face.jpg", "rb").read()).decode() req = urllib.request.Request( "http://127.0.0.1:8083/api/detect", data=json.dumps({"image": img}).encode(), headers={"Content-Type": "application/json"}, ) print(urllib.request.urlopen(req).read().decode()) ``` ## 4. Mobile — after the demo compiles Keep the **demo application ID** so the included license key license works. Call this on a **background** thread. {% tabs %} {% tab title="Android Face Recognition" %} ```kotlin Thread { FaceRecognitionSDK.getMachineCode(context) var code = FaceRecognitionSDK.setActivation(context, "license key") // demo key from the repo if (code == FaceRecognitionSDK.SDK_SUCCESS) { code = FaceRecognitionSDK.init(context) } val faces = FaceRecognitionSDK.faceDetection(bitmap, FaceDetectionParam()) val template = FaceRecognitionSDK.templateExtraction(bitmap, faces[0]) val score = FaceRecognitionSDK.similarity(template, template) }.start() ``` Install: [Face Recognition Android SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk). {% endtab %} {% tab title="Flutter Face Recognition" %} ```dart import 'package:face_recognition_sdk/face_recognition_sdk.dart'; Future tryOnce(String imagePath, String license) async { await getMachineCode(); if (await setActivation(license) != sdkSuccess) return; if (await init() != sdkSuccess) return; final faces = await faceDetection(imagePath); final t1 = await templateExtraction(imagePath, faces.first); final t2 = await templateExtraction(imagePath, faces.first); final score = await similarity(t1, t2); } ``` Install: [Face Recognition Flutter SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-flutter-sdk). {% endtab %} {% tab title="Android ID Document" %} ```kotlin Thread { DocumentReaderSDK.getMachineCode(context) var code = DocumentReaderSDK.setActivation(context, "license key") if (code == DocumentReaderSDK.SDK_SUCCESS) { code = DocumentReaderSDK.init(context) } val json = DocumentReaderSDK.recognize(frontBitmap, null, "none") }.start() ``` `locateDocument` is overlay-only (no OCR). Install: [ID Document Recognition Android SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-android-sdk). {% endtab %} {% endtabs %} ### Related documentation * [HTTP API](/integration/http-api) · [Deploy and host](/integration/deploy-and-host) · [Choose a product](/getting-started/choose-a-product) * [Glossary](/help/resources/glossary) · [Status codes](/help/resources/status-codes) · [Troubleshooting](/help/resources/troubleshooting) * [Request a License](/help/request-a-license-and-support) # Face SDK Faceplugin Face SDK: on-premise face recognition, standalone face liveness, and combined Recognition + Liveness for mobile and server (ports 8083 / 8084). ### Overview **Faceplugin Face SDK** covers **face recognition**, **standalone face liveness**, and **recognition + liveness** in one server process. Images are processed on the device or on your server — not in Faceplugin’s cloud. Recognition is evaluated on **NIST FRVT** (Face Recognition Vendor Test). **What it can do:** [Capabilities](/products/face-recognition-sdk/capabilities). Then pick a mode: * [**Recognition**](/products/face-recognition-sdk/recognition) — recognition-only server API on **8083** (`faceplugin/face-recognition`) * [**Liveness**](/products/face-recognition-sdk/liveness-detection-sdk) — standalone face PAD on **8084** / mobile (no matching) * [**Recognition + Liveness**](/products/face-recognition-sdk/recognition-and-liveness) — mobile Identify + 2D liveness, and server match + `/api/liveness` on **8083** (**recommended** for eKYC) ```mermaid flowchart LR Camera --> Detect Detect --> Liveness2D Liveness2D --> Embedding Embedding --> Identify Identify --> Result ``` ### Features * [x] Face Detection * [x] Face Landmark Detection * [x] Face Template Extraction * [x] Face Template Matching * [x] Live 1:N Identify (mobile) * [x] Liveness Detection (passive 2D on mobile Identify) * [x] Pose Estimation * [x] On-premise Face Recognition API (port **8083**) ### Modes Start with [Capabilities](/products/face-recognition-sdk/capabilities), then open a mode.
CapabilitiesRecognition, liveness, and recognition + liveness in one place.Capabilities
RecognitionRecognition-only server (no /api/liveness).Recognition
LivenessStandalone face anti-spoofing on mobile and port 8084.Liveness
Recognition + LivenessMobile + combined server — recommended for eKYC.Recognition + Liveness
Typical call order on **mobile**: `setActivation` → `init` → detect / extract template → store templates in **your** database → `similarity` or VideoWorker (live 1:N). Identify default **0.67**. Liveness default **0.5**. Typical call order on **Linux / Windows**: `GET /api/machinecode` → `POST /api/activate` → `POST /api/detect` / `match` / `similarity`. There is **no** server-side 1:N gallery (`POST /api/identify` does not exist). ### FAQ **Can face recognition work completely offline?** Yes. After you activate with a license key, matching does not need the internet. See [Capabilities](/products/face-recognition-sdk/capabilities). **Does this SDK include liveness?** Mobile Identify includes passive 2D liveness. For standalone face anti-spoofing, use the [Face Liveness Detection SDK](/products/face-recognition-sdk/liveness-detection-sdk). On the server you can use combined [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux), which provides both services on port **8083**. **Is there a Face Recognition API?** Yes — Linux Docker and Windows HTTP on port **8083**. See [Linux](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk), [Windows](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk), and combined [Face Recognition + Liveness Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) / [Windows](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-windows). **Does the server SDK support 1:N identification?** The server SDK does not provide a built-in 1:N gallery or `POST /api/identify` endpoint. Instead, store face templates in your own database. When you need to identify a person, compare the probe template against your stored templates using `/api/similarity` and determine the best match in your application. ### Use cases * **Access control** — enroll face templates, then live 1:N Identify at a door or gate (mobile) * **Attendance** — enroll staff once; match camera frames against your person database * **App login** — 1:1 selfie match against a stored template (`similarity` / `POST /api/match`) * **KYC selfie match** — after ID OCR, compare portrait crop to a live selfie (with [Document Recognition](/products/id-document-recognition-sdk) and optional [Face Liveness](/products/face-recognition-sdk/liveness-detection-sdk)) * **Fraud checks** — still-image detect / match / similarity on your server (port **8083**) ### Related documentation * [Capabilities](/products/face-recognition-sdk/capabilities) · [Recognition](/products/face-recognition-sdk/recognition) · [Liveness](/products/face-recognition-sdk/liveness-detection-sdk) · [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) · [ID Document SDK](/products/id-document-recognition-sdk) * [Request a License](/help/request-a-license-and-support) · [Try it](/getting-started/try-it) · [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) * [Status codes](/help/resources/status-codes) # Capabilities Faceplugin Face SDK capabilities: face recognition (1:1, mobile 1:N Identify), standalone face liveness (PAD), and combined Recognition + Liveness on port 8083. What the Faceplugin **Face SDK** can do — **recognition**, **liveness**, and **recognition + liveness** — before you pick a platform. | Mode | What you get | Start install | | -------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------- | | **Recognition** | Detect, templates, 1:1 match, mobile 1:N Identify | [Recognition](/products/face-recognition-sdk/recognition) | | **Liveness** | Standalone passive face anti-spoofing (no gallery) | [Liveness](/products/face-recognition-sdk/liveness-detection-sdk) | | **Recognition + Liveness** | Matching and `POST /api/liveness` in one server process | [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) | ```mermaid flowchart LR Camera --> Detect Detect --> Liveness2D Liveness2D --> Embedding Embedding --> Identify Identify --> Result ``` ## Recognition After you activate with a license key, face detection, template extraction, and matching run **offline** on the device or on **your** Windows/Linux host. Images are not sent to a Faceplugin cloud. The algorithm is evaluated on **NIST FRVT** (as stated across Faceplugin Face Recognition docs). | Mode | Where | How | | ---------------- | ----------------- | --------------------------------------------------------------------------------------------------- | | **1:1** | Mobile and server | Extract two templates → `similarity` / `POST /api/similarity`, or `POST /api/match` with two images | | **1:N Identify** | Mobile demos | VideoWorker + templates you store in **your** database (demo default match threshold **0.67**) | On **Linux / Windows**, the HTTP API is still-image **detect / quality / feature / match / similarity**. There is **no** server-side `POST /api/identify` gallery — you store templates and call similarity yourself. `templateExtraction` / `POST /api/feature` generates face templates that you can store in **your own database**. Faceplugin does not host your users' face data or provide a cloud-based person gallery. Mobile **1:N Identify** includes passive 2D liveness (default threshold **0.5**) as part of the identify flow. That is **not** the same as the standalone Liveness product below. ### Recognition API (port 8083) | Route | Role | | ---------------------- | ------------- | | `GET /api/machinecode` | Machine code | | `POST /api/activate` | Activate | | `POST /api/detect` | Detect faces | | `POST /api/quality` | Quality | | `POST /api/feature` | Template | | `POST /api/match` | Two images | | `POST /api/similarity` | Two templates | Image: `faceplugin/face-recognition`. See [Linux](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) · [Windows](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk). ## Liveness (standalone PAD) Standalone **passive** presentation-attack detection: scores a camera frame or JPEG **without** a smile / turn-head challenge. These docs do **not** claim iBeta certification. Contact Faceplugin if you need a certification statement. Detects attack types including: * Printed photos * Screen replays * 3D models / masks * Deepfake-style video (one type of spoof — not a separate deepfake product) Score **≥ 0.5** → Real / pass (server default threshold in these docs). | Surface | Behavior | | ------------------- | ------------------------------------------------------------- | | **Android / iOS** | Live camera + VideoWorker / `faceDetection` for anti-spoofing | | **Linux / Windows** | `POST /api/liveness` with one RGB JPEG on port **8084** | There is **no** public Face Liveness Flutter or React Native SDK. Use native Liveness, or 2D liveness on Face Recognition Identify. ```bash curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` Images: `faceplugin/face-liveness`. See [Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Windows](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk). ## Recognition + Liveness (one server process) One container / process on port **8083**: all recognition routes **plus** `POST /api/liveness`. Image: `faceplugin/face-recognition-liveness-sdk`. See [Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) · [Windows](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-windows). ## Which mode to pick | Need | Mode | | --------------------------------------------------------- | --------------------------------------------------------------------- | | Enroll / 1:N match (mobile Identify includes 2D liveness) | **Recognition** | | Anti-spoofing only (no gallery) | **Liveness** | | Recognition + anti-spoofing in **one** server process | **Recognition + Liveness** | | Document authenticity (ID spoof) | [ID Document SDK](/products/id-document-recognition-sdk/capabilities) | ## Platforms | Mode | Surfaces | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Recognition | [Server](/products/face-recognition-sdk/recognition/server-sdk) (`faceplugin/face-recognition`) · [Open Source](/products/face-recognition-sdk/recognition/open-source-windows-and-linux) | | Liveness | [Mobile](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk) · [Server](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk) (**8084**) | | Recognition + Liveness | [Mobile](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Linux](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) · [Windows](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-windows) · [.NET](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-dot-net-sdk) | ## Use cases * **Access control / attendance** — enroll templates; live 1:N Identify * **KYC selfies** — passive anti-spoofing before or with face match * **Server fraud checks** — still-image detect / match / similarity on **8083**, or liveness on **8084** / combined **8083** ## FAQ **Can face recognition work completely offline?** Yes, after license activation. **Is there a Face Recognition API?** Yes — HTTP on port **8083**. **Server-side 1:N gallery?** No. Store templates in your DB; call `/api/similarity`. **Difference between Identify 2D liveness and Face Liveness?** Identify embeds 2D liveness in matching; standalone Liveness is anti-spoofing only (port **8084**). ### Related documentation * [Face SDK](/products/face-recognition-sdk) · [Try it](/getting-started/try-it) · [Glossary](/help/resources/glossary) * [ID Document capabilities](/products/id-document-recognition-sdk/capabilities) * [Request a License](/help/request-a-license-and-support) # Recognition Faceplugin Face SDK — Recognition only. Server Face Recognition API on port 8083 (no /api/liveness). **Recognition only** server products: detect, quality, templates, 1:1 match / similarity. Port **8083**. These images do **not** expose `POST /api/liveness`. * **Capabilities:** [Face SDK capabilities](/products/face-recognition-sdk/capabilities) (Recognition section) * **Server:** [Server SDK](/products/face-recognition-sdk/recognition/server-sdk) — [Linux](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) (`faceplugin/face-recognition`) · [Windows](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) * **Open source:** free Python samples — [Open Source](/products/face-recognition-sdk/recognition/open-source-windows-and-linux) Mobile Face Recognition apps include **2D liveness on Identify** — they live under [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness), not here. For standalone anti-spoofing only see [Liveness](/products/face-recognition-sdk/liveness-detection-sdk). For match + `/api/liveness` in one server process see [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness). # Server Faceplugin Face Recognition Server SDK and Face Recognition API. On-premise HTTP for Windows, Linux Docker, and .NET. detect, match, similarity on port 8083. Offline after license activation. Face **Recognition** as an HTTP API (or .NET bindings) on **your** machine. Still-image detect, quality, template extract, 1:1 match, and template similarity. There is **no** server-side 1:N gallery (`POST /api/identify` does not exist). Typical call order: `GET /api/machinecode` → send machine code → `POST /api/activate` → `POST /api/detect` / `match` / `similarity`. Default port **8083**. For recognition **and** liveness in one process, see [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness). For on-device apps, use [Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk). Open-source Python samples: [Open Source](/products/face-recognition-sdk/recognition/open-source-windows-and-linux).
Linux SDKDocker Hub image faceplugin/face-recognition. Same HTTP API as Windows.linux-docker.pngLinux
Windows SDKCommercial HTTP API on port 8083. CPU only. No Docker.windows.pngWindows
.NET SDK.NET MAUI and C# bindings. Follow the public GitHub README.dotnet.png.NET
```mermaid flowchart LR JPEG --> Detect Detect --> Embedding Embedding --> Match Match --> Result ``` ### FAQ **Is this a Face Recognition API?** Yes. HTTP on port **8083**: `POST /api/detect`, `/api/match`, `/api/similarity`. **Is there server-side 1:N?** No. There is no `POST /api/identify` gallery. Store templates in **your** database. **Docker vs Windows?** Same routes. Windows has no Docker; Linux uses `faceplugin/face-recognition`. **Recognition + liveness in one process?** See [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness). Or keep Face Liveness on **8084** as a separate product. ### Related documentation * [Capabilities](/products/face-recognition-sdk/capabilities) · [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Face Recognition SDK](/products/face-recognition-sdk) · [Glossary](/help/resources/glossary) * [Face Liveness Detection Server SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk) * [ID Document Recognition Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Linux Faceplugin Face Recognition API for Linux Docker. On-premise detect, match, and similarity on port 8083. Offline after license activation. Fully on-premise **Face Recognition API for Linux / Docker**. Image: `faceplugin/face-recognition`. Default port **8083**. This product is **recognition only**. For recognition and liveness in the **same** container, use [Face Recognition + Liveness Linux SDK](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) (`faceplugin/face-recognition-liveness-sdk`). Or run [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) on port **8084** as a second container. All processing stays on your server. **No** biometric data is sent to Faceplugin cloud. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Pull from Docker Hub (no Google Drive download) ``` sudo docker pull faceplugin/face-recognition:latest sudo docker run -d --name faceplugin-face-recognition \ --shm-size=2gb --privileged \ -p 8083:8083 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/face-recognition:latest ``` On Docker Desktop (macOS/Windows) omit the `/etc/machine-id` volume. {% endstep %} {% step %} ## Confirm health (no license yet) ``` curl -s http://127.0.0.1:8083/api/health ``` {% endstep %} {% step %} ## Copy the machine code ``` curl -s http://127.0.0.1:8083/api/machinecode ``` Send machine code to Faceplugin. Docker and local host codes are **different**. {% endstep %} {% step %} ## Activate Put your key in `license.txt`, then: ``` curl -s -X POST http://127.0.0.1:8083/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% endstepper %} ### Run multiple containers with one license You only need this section if you want to run multiple Face Recognition 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: ```bash sudo docker run -d --name faceplugin-face-recognition-2 \ --shm-size=2gb --privileged \ -p 8084:8083 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/face-recognition: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/FaceRecognition-Docker.git cd FaceRecognition-Docker ``` Put the [Google Drive runtime](https://drive.google.com/drive/folders/1NVq0psW8PLfEX58FWNE-RKFWfCZdOMmz) 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. Needs glibc **2.38+** (for example Ubuntu 24.04). ``` pip3 install -r requirements.txt ./run.sh ``` {% hint style="info" %} Control routes (`/api/health`, `/api/machinecode`, `/api/activate`, `/api/licenseStatus`) return a JSON **envelope**. Process POSTs (`/api/detect`, `/api/quality`, …) return **engine JSON** as the HTTP body. {% endhint %} ### License Licenses are **offline**. [Request a License & Support](/help/request-a-license-and-support). ### Try it ```bash curl -s http://127.0.0.1:8083/api/health IMG=$(base64 -w0 face.jpg) # macOS: base64 -i face.jpg curl -s -X POST http://127.0.0.1:8083/api/detect \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" curl -s -X POST http://127.0.0.1:8083/api/match \ -H 'Content-Type: application/json' \ -d "{\"image1\":\"$IMG\",\"image2\":\"$IMG\"}" ``` **Postman:** import `postman/FaceRecognition-API.postman_collection.json` from the repo. Base URL `http://127.0.0.1:8083`. Paths have **no** `/v1`. **Gradio (host only):** the Docker image is API-only. On the host: ``` pip3 install -r requirements-demo.txt DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python3 demo.py ``` Open . Tabs: Detect, Quality, Match. ### Integrate into your own app | Path | When to use | | ------------------- | -------------------------------------------------------------------------- | | **HTTP** (`app.py`) | Any language. Keep this API running and `POST` base64 JPEGs. | | **`sdk.py`** | Python on the **same** Linux host as `lib/cpu/` (or inside the container). | You do **not** need Gradio in production. ### 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/detect` | Detect faces | | `POST /api/quality` | Quality checks | | `POST /api/feature` | Extract template | | `POST /api/match` | Compare two photos | | `POST /api/similarity` | Compare two templates | Full reference: [Face Recognition HTTP API](/integration/http-api/face-recognition). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). Process POSTs return **engine JSON** as the body. There is **no** `POST /api/identify` (no server-side 1:N gallery). Python: ```python import sdk print(sdk.get_machine_code()) sdk.activate("license.txt") sdk.init_sdk() print(sdk.get_license_status()) print(sdk.detect(base64_image)) print(sdk.match(image1, image2)) ``` Call order: `get_machine_code` → `activate` → `init_sdk` → detect / quality / feature / match / similarity. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Is this a Face Recognition API?** Yes. Docker image `faceplugin/face-recognition`, port **8083**: `POST /api/detect`, `/api/match`, `/api/similarity`. **Machine code?** `GET /api/machinecode` returns machine code. Docker and host codes differ. **Server-side 1:N?** No. There is no `POST /api/identify` gallery. ### Related documentation * [Face Recognition HTTP API](/integration/http-api/face-recognition) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements) * [Faceplugin Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Windows](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) · [Glossary](/help/resources/glossary) * [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) * [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Architecture](/integration/deploy-and-host/architecture) · [SDK comparison](/help/comparisons) # Windows Faceplugin Face Recognition Windows SDK. Fully on-premise HTTP API on port 8083. detect, quality, feature, match, similarity. No Docker. Fully on-premise **commercial Face Recognition HTTP API for Windows**. Default port **8083**. Gradio **9003**. No Docker on Windows. This is not the [Open Source Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/open-source-windows-and-linux/open-source-face-recognition-windows-sdk). For recognition and liveness in the **same** process, use [Face Recognition + Liveness Windows SDK](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-windows). Or run [Face Liveness Detection Windows SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) on port **8084** as a second process. All processing stays on your server. **No** biometric data is sent to Faceplugin cloud. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Copy the runtime Copy the CPU libraries from [Google Drive](https://drive.google.com/drive/folders/12i5d2-TahuJumre2EVYqWO8cIi_unTBz) into `lib\cpu\`. {% endstep %} {% step %} ## Install and run ``` pip install -r requirements.txt run.bat ``` {% endstep %} {% step %} ## Copy the machine code ``` curl -s http://127.0.0.1:8083/api/machinecode ``` Send machine code to Faceplugin. Copy it from the terminal if curl is not available. {% endstep %} {% step %} ## Activate ``` curl -s -X POST http://127.0.0.1:8083/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% endstepper %} {% hint style="info" %} Control routes (`/api/health`, `/api/machinecode`, `/api/activate`, `/api/licenseStatus`) return a JSON **envelope**. Process POSTs (`/api/detect`, `/api/quality`, …) return **engine JSON** as the HTTP body. {% endhint %} ### APIs Same routes as [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk): | 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/detect` | Detect faces | | `POST /api/quality` | Quality checks | | `POST /api/feature` | Extract template | | `POST /api/match` | Compare two photos | | `POST /api/similarity` | Compare two templates | Full reference: [Face Recognition HTTP API](/integration/http-api/face-recognition). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). Process POSTs return **engine JSON** as the body. There is **no** `POST /api/identify` (no server-side 1:N gallery). ### Try it ```bash curl -s http://127.0.0.1:8083/api/health IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8083/api/detect \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" curl -s -X POST http://127.0.0.1:8083/api/match \ -H 'Content-Type: application/json' \ -d "{\"image1\":\"$IMG\",\"image2\":\"$IMG\"}" ``` **Postman:** import `postman/FaceRecognition-API.postman_collection.json` from the repo. Base URL `http://127.0.0.1:8083`. Paths have **no** `/v1`. **Gradio (host only):** `DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python demo.py`. Open . You do **not** need Gradio in production. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Face Recognition API on Windows?** Yes. Port **8083**, same routes as Linux. No Docker. **Offline?** Yes after `POST /api/activate` with a license key bound to this host's machine code. ### Related documentation * [Faceplugin Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Linux](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) · [Glossary](/help/resources/glossary) * [Face Liveness Detection Windows SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) * [ID Document Recognition Windows SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-windows-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Open Source Free on-premise Python Face Recognition sample for Windows and Linux. Detect, embed, and compare faces locally. Lower accuracy than Faceplugin’s commercial HTTP API on port 8083. ### Code {% embed url="" %} ### Overview The **Open Source Face Recognition SDK** is a free Python sample for Windows and Linux. It detects faces, extracts embeddings, and compares them on your machine (no Faceplugin cloud). Accuracy is lower than the commercial Face Recognition SDK. Contact Faceplugin if you need the higher-accuracy native engine. This sample is **not** the commercial Android/iOS or HTTP engine. ### Setup #### Prerequisites * **Python 3.9 or higher** * **Anaconda** (recommended for dependency management) * **Windows or Linux** operating system #### Setup Instructions 1. **Install Anaconda** (if not already installed) ``` # Download from: https://www.anaconda.com/products/distribution ``` 2. **Create and activate conda environment** ``` conda create -n facesdk python=3.9 conda activate facesdk ``` 3. **Install dependencies** ``` pip install -r requirements.txt ``` 4. **Test the installation** ``` python run.py ``` *** ### Quick Start #### Basic Usage ``` from face_recognition_sdk import FaceRecognition # Initialize the SDK face_sdk = FaceRecognition() # Process an image image_path = "path/to/your/image.jpg" face_info = face_sdk.GetImageInfo(image_path, faceMaxCount=10) # Compare two faces similarity = face_sdk.get_similarity(feature1, feature2) ``` #### Example: Face Comparison ``` # Compare two images image1 = "test/1.jpg" image2 = "test/2.png" # Get face information from both images faces1 = face_sdk.GetImageInfo(image1, faceMaxCount=1) faces2 = face_sdk.GetImageInfo(image2, faceMaxCount=1) if faces1 and faces2: # Compare the first face from each image similarity = face_sdk.get_similarity(faces1[0]['embedding'], faces2[0]['embedding']) print(f"Similarity: {similarity}%") # Check if it's the same person (threshold = 75) is_same_person = similarity >= 75 print(f"Same person: {is_same_person}") ``` *** ### APIs ### Core Functions **`GetImageInfo(image_path, faceMaxCount)`** Extracts face information from an image. **Parameters:** * `image_path` (str): Path to the input image * `faceMaxCount` (int): Maximum number of faces to detect **Returns:** * List of dictionaries containing: * `bbox`: Face bounding box coordinates * `landmarks`: Facial landmark points * `embedding`: Feature embedding vector **`get_similarity(feature1, feature2)`** Compares two face feature embeddings. **Parameters:** * `feature1` (array): First face embedding * `feature2` (array): Second face embedding **Returns:** * Similarity score (0-100), where higher values indicate greater similarity #### Configuration * **Default Threshold**: 75 (for determining if two faces belong to the same person) * **Supported Formats**: JPG, PNG, BMP, TIFF * **Face Detection**: Automatic detection of multiple faces per image
### FAQ **Is this the commercial SDK?** No. Contact Faceplugin for the higher-accuracy native engine. **Does it run on-premise?** Yes. Processing stays on the user’s Windows or Linux machine. ### Related documentation * [Faceplugin Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Glossary](/help/resources/glossary) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Linux Faceplugin open-source Face Recognition Linux SDK. Free on-premise Python sample. Lower accuracy than the commercial Docker Face Recognition API. ### Code {% embed url="" %} Free open-source Face Recognition Linux SDK {% endembed %} ### Overview Free **open-source** Face Recognition sample for Linux (Python). Detect faces, extract embeddings, and compare them **on your machine** — no Faceplugin cloud. Accuracy is **lower** than the commercial [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk). Contact Faceplugin if you need the higher-accuracy native engine. ### Setup Please download anaconda on your computer and install it. We used Linux machine without GPU for testing 1. **Create anaconda environment** `conda create -n facesdk python=3.9` 2. **Activate env** `conda activate facesdk` 3. **Install dependencies** `pip install -r requirements.txt` 4. **In `face_util/faceutil.py`, confirm the Linux library path points to `libFaceUtil.so`** ``` dll_path = os.path.abspath(os.path.dirname(__file__)) + '/C/libFaceUtil.so' ``` (Windows uses `'/C/FaceUtil.dll'` instead — see the Windows page.) 5. **Compare face images in the** `test` **directory** `python run.py` ### APIs and Parameters * **GetImageInfo(image, faceMaxCount):** returns face bounding boxes, landmarks and feature embedding * **get\_similarity(feat1, feat2):** returns similarity between two feature embeddings. 0 to 100 * **Threshold:** value to determine if two embeddings belong to same person, default = 75 ### FAQ **Same accuracy as Docker Hub?** No. Use [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) (`faceplugin/face-recognition`) for the commercial Face Recognition API. ### Related documentation * [Faceplugin Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Open Source Windows](/products/face-recognition-sdk/recognition/open-source-windows-and-linux/open-source-face-recognition-windows-sdk) · [Glossary](/help/resources/glossary) * Lower accuracy than the commercial [Linux HTTP API](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk). * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Windows Faceplugin open-source Face Recognition Windows SDK. Free on-premise Python sample. Lower accuracy than the commercial HTTP API on port 8083. ### Code {% embed url="" %} Free open-source Face Recognition Windows SDK {% endembed %} ### Overview Free **open-source** Face Recognition sample for Windows (Python). Detect faces, extract embeddings, and compare them **on your machine** — no Faceplugin cloud. Accuracy is **lower** than the commercial [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk). Contact Faceplugin if you need the higher-accuracy native engine. The Windows library path in `face_util/faceutil.py` should be: ``` dll_path = os.path.abspath(os.path.dirname(__file__)) + '/C/FaceUtil.dll' ``` ### Setup Please download anaconda on your computer and install it. We used Windows machine without GPU for testing 1. **Create anaconda environment** `conda create -n facesdk python=3.9` 2. **Activate env** `conda activate facesdk` 3. **Install dependencies** `pip install -r requirements.txt` 4. **Compare face images in the** `test` **directory** `python run.py` ### APIs and Parameters * **GetImageInfo(image, faceMaxCount):** returns face bounding boxes, landmarks and feature embedding * **get\_similarity(feat1, feat2):** returns similarity between two feature embeddings. 0 to 100 * **Threshold:** value to determine if two embeddings belong to same person, default = 75 ### FAQ **Same accuracy as the commercial API?** No. Use [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) on port **8083** for the commercial engine. ### Related documentation * [Faceplugin Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Open Source Linux](/products/face-recognition-sdk/recognition/open-source-windows-and-linux/open-source-face-recognition-linux-sdk) · [Glossary](/help/resources/glossary) * Lower accuracy than the commercial [Windows HTTP API](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk). * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Liveness Faceplugin Face Liveness Detection SDK and anti-spoofing. On-premise passive liveness for Android, iOS, Windows, and Linux Docker. POST /api/liveness on port 8084. ### Overview **Faceplugin Face Liveness Detection SDK** is an on-premise **face anti-spoofing** / presentation-attack detection (PAD) engine. It answers: is a **live person** in front of the camera, or a printout, phone screen, 3D mask, or deepfake-style video? **What it can do:** [Face SDK capabilities](/products/face-recognition-sdk/capabilities) (Liveness section) — passive anti-spoofing, mobile vs server, and when to use it versus Face Recognition Identify. This product is **passive** anti-spoofing: no smile / turn-head challenge. These docs do **not** claim iBeta certification. Contact Faceplugin if you need a certification statement. Active challenge demos on GitHub are **not** this product. Optional active prompts on some Face Recognition Identify flows also are not this SDK. This SDK is **standalone**. It does **not** enroll people or run 1:N. If you already use Face Recognition Identify on mobile, that flow already includes **passive 2D liveness**. Choose this product when you need anti-spoofing **without** face matching. ```mermaid flowchart LR Frame --> PAD PAD --> Score Score --> RealOrSpoof ``` Capable of detecting: * **Printed photos** * **Screen replays** * **3D models** * **Deepfakes** (handled as one type of spoof attack — not a separate deepfake product) **Mobile** apps run a live camera (VideoWorker plus `faceDetection`). **Linux and Windows** expose a Face Liveness **API**: one RGB JPEG over `POST /api/liveness`. Score **0.5 or higher** is Real / pass. ### Platforms Start with [Face SDK capabilities](/products/face-recognition-sdk/capabilities), then **Mobile SDK** or **Server SDK**.
CapabilitiesFace SDK capabilities — Recognition, Liveness, Recognition + Liveness.Capabilities
Mobile SDKAndroid and iOS. Live camera anti-spoofing.Mobile
Server SDKWindows and Linux / Docker. JPEG over HTTP on port 8084.Server
### FAQ **What is passive liveness detection?** The engine scores a camera frame or JPEG without a user challenge animation. See [Capabilities](https://github.com/gentlebear0988/temp-docs/tree/main/faceplugin-docs/liveness-detection-sdk/capabilities.md). **What is the difference between this and Face Recognition liveness?** Face Recognition mobile Identify includes 2D liveness as part of matching. This product is anti-spoofing only. **Does it require the internet?** No, after license activation. ### Use cases * **KYC / onboarding selfies** — confirm a live person before face match (`faceDetection` / `POST /api/liveness`) * **Banking and fintech** — block photo and screen replay attacks on selfie capture * **Access control** — reject printouts and phone-screen spoofs at entry * **Exam proctoring** — score camera frames for presentation attacks without a challenge animation * **Fraud prevention** — JPEG anti-spoofing on your server (port **8084**) ### Related documentation * [Face SDK capabilities](/products/face-recognition-sdk/capabilities) · [Face SDK](/products/face-recognition-sdk) · [ID Document SDK](/products/id-document-recognition-sdk) * [Request a License](/help/request-a-license-and-support) · [Try it](/getting-started/try-it) · [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) * [Status codes](/help/resources/status-codes) # Mobile Faceplugin Face Liveness Detection Mobile SDK. On-premise anti-spoofing for Android and iOS. Passive liveness against photos, screens, 3D masks, and deepfakes. Standalone presentation-attack detection on Android and iOS. The demo scores whether the face is **real**. It does not enroll people or run 1:N search. Live camera (VideoWorker plus `faceDetection`). Score **0.5 or higher** is treated as Real / pass. If you already use Face Recognition Identify on mobile, that flow already includes **passive 2D liveness**. Choose this product when you need anti-spoofing **without** enrollment. For JPEG-over-HTTP on Windows, Linux, and Docker, use [Server SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk).
Android SDKNative AAR. Liveness, Settings, and About screens.android.pngAndroid
iOS SDKThree frameworks. Same anti-spoofing flow as Android.apple-logo-3-300x300.pngiOS
```mermaid flowchart LR Frame --> PAD PAD --> Score Score --> RealOrSpoof ``` ### FAQ **Is this active liveness?** No. This product is **passive** anti-spoofing (no smile / turn-head challenge). **Flutter / React Native?** There is no public Face Liveness Flutter or React Native SDK. Use native Android/iOS, or 2D liveness on Face Recognition Identify. ### Related documentation * [Capabilities](https://github.com/gentlebear0988/temp-docs/tree/main/faceplugin-docs/liveness-detection-sdk/capabilities.md) · [Faceplugin Face Liveness Detection Server SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk) · [Face Liveness Detection SDK](/products/face-recognition-sdk/liveness-detection-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Android Faceplugin Face Liveness Detection Android SDK. On-premise PAD against photos, screens, masks, and deepfakes. AAR, setActivation, init, faceDetection, detect. Fully on-premise **Face Liveness SDK for Android** (presentation-attack detection). The demo does not enroll people or run 1:N search. It scores whether the face is real. | What | Id | | ------------------------- | ------------------------------------------------ | | Android demo package name | `com.faceplugin.faceliveness` | | Public Java class | `com.faceplugin.facelivenesssdk.FaceLivenessSDK` | Keep the demo package name **`com.faceplugin.faceliveness`** so the sample key works. ### Code {% embed url="" %} ### Setup 1. Copy the SDK (`libfacesdk` folder) to the `root` folder in your project. Place `facelivenessdk.aar` from [Google Drive](https://drive.google.com/drive/folders/1x3jt02f-YHsk4WD_QlnKJSx5uQ5Ds4xH) inside `libfacesdk/`. 2. Add SDK to the project in `settings.gradle` ``` rootProject.name = "YourProjectName" include ':app' include ':libfacesdk' ``` 3. Add dependency to your `build.gradle` ``` implementation project(path: ':libfacesdk') ``` 4. minSdk **24**, `useLegacyPackaging = true`, CAMERA permission. Call **setActivation → init** on a **background** thread. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ### APIs #### setActivation: This API is used to activate the SDK ```java public static int setActivation(Context context, String license); ``` | **Input** |
  • context (Context): Android Context
  • license (String): The license string (license key)
| | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** |

The SDK activation status code.

  • 0: Success
  • 1: Invalid license
  • 2: Expired
  • 3: Not activated
  • 4: Init failed
| #### init: This API is used to initialize the SDK ```java public static int init(Context context) throws IOException; ``` #### getMachineCode: This API is used to retrieve the machine code ```java public static String getMachineCode(Context context); ``` #### getLicenseStatus: This API is used to read license status ```java public static String getLicenseStatus(); public static boolean allowsLiveness(); public static String lastEngineError(); ``` Use `allowsLiveness()` before Capture. #### faceDetection: This API is used to detect faces and determine if the faces are real or fake ```java public static List faceDetection(Bitmap bitmap, FaceDetectionParam param); ``` | **Input** |
  • bitmap (Bitmap): The Bitmap image
  • param (FaceDetectionParam): Parameters for face detection
| | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Return value** | A list of **FaceBox** objects representing the detected faces and their liveness scores. | **FaceDetectionParam** ```java public class FaceDetectionParam { public boolean check_liveness = false; // set it to true to check liveness public int check_liveness_level = 0; // 0: accurate model, 1: light model public boolean check_eye_closeness = false; public boolean check_face_occlusion = false; public boolean check_pose = true; public boolean check_landmarks = true; public boolean check_quality = false; } ``` **FaceBox** ```java public class FaceBox { public int x1, y1, x2, y2; public float liveness, yaw, roll, pitch; public float face_quality, face_luminance, score; public int trackId; public String livenessLabel; } ``` The liveness score ranges from 0.0 to 1.0. If it's greater than the threshold, it's real face. Demo default threshold is **0.5**. #### detect: This API is used to detect faces and return engine JSON ```java public static String detect(Bitmap bitmap, boolean crop, int flags); ``` `detect` requires a liveness-capable license. #### VideoWorker: This API is used for the live camera HUD The demo does **not** enroll. VideoWorker match DB is empty. Use it to keep a live track while you still score with `faceDetection`: `startVideoWorker` → `addVideoWorkerFrame` → `stopVideoWorker`. #### deinit: This API is used to unload the engine ```java public static int deinit(); ``` ### Run the demo 1. Place `facelivenessdk.aar` in `libfacesdk/` (see Setup). 2. Keep the demo package name **`com.faceplugin.faceliveness`**. 3. Run on a **physical** phone. 4. Home tiles: **Liveness**, Settings, About. The demo does **not** enroll people or run 1:N search. ### Screenshots | Home | Liveness | Settings | About | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Face Liveness Android home | Faceplugin Face Liveness live camera | Faceplugin Face Liveness settings | Faceplugin Face Liveness About | ### License Licenses are **offline**. Request a new license key for your own app. Use `allowsLiveness()` before Capture. {% hint style="warning" %} `FaceDetectionParam.check_liveness` defaults to **false**. Set it to **true** or you will not get a liveness score. {% endhint %} ### Try it (after the demo compiles) ```java FaceDetectionParam param = new FaceDetectionParam(); param.check_liveness = true; param.check_liveness_level = 0; // 0 accurate, 1 light List faces = FaceLivenessSDK.faceDetection(bitmap, param); if (!faces.isEmpty() && faces.get(0).liveness >= 0.5f) { // Real } ``` [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Passive or active?** **Passive** anti-spoofing. Score the camera frame; no smile / turn-head challenge on this product. **Threshold?** Treat **0.5** or higher as Real / pass unless Faceplugin support gives you a different recommended threshold. ### Related documentation * [Faceplugin Face Liveness Detection Mobile SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk) · [iOS](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-ios-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Android SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) * [ID Document Recognition Android SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-android-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # iOS Faceplugin Face Liveness Detection iOS SDK. On-premise PAD against photos, screens, masks, and deepfakes. Xcode frameworks, setActivation, initSDK, detectImage. Fully on-premise **Face Liveness SDK for iOS**. Native class: `FaceLivenessSDK`. | What | Id | | ------------------------------------------------ | ----------------------------------------------- | | iOS demo app (Xcode `PRODUCT_BUNDLE_IDENTIFIER`) | `com.faceplugin.faceliveness.app` | | Android demo package name | `com.faceplugin.faceliveness` | | SDK class / framework | `FaceLivenessSDK` in `facelivenessdk.framework` | Keep the iOS demo bundle **`com.faceplugin.faceliveness.app`** so the included license works. Request a new license key if you change it. ### Code {% embed url="" %} ### Setup 1. Unzip the frameworks from [Google Drive](https://drive.google.com/drive/folders/1HzREOmFg9kBLbuso1e57j8Hk5Jk41kyr): `facelivenessdk.framework`, `FaceLivenessEngine.framework`, `onnxruntime.framework`. 2. Add the SDK frameworks to the project in Xcode (**Embed & Sign**). 3. Add `FaceLivenessSDK-Bridging-Header.h` to Build Settings. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ### APIs #### setActivation: This API is used to activate the SDK ```objectivec +(int)setActivation:(NSString*)license; ``` | **Input** |
  • license (NSString\*): The license string (license key)
| | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** |

The SDK activation status code.

  • 0: Success
  • 1: Invalid license
  • 2: Expired
  • 3: Not activated
  • 4: Init failed
| #### initSDK: This API is used to initialize the SDK ```objectivec +(int)initSDK; ``` #### getMachineCode: This API is used to retrieve the machine code ```objectivec +(NSString*)getMachineCode; ``` #### getLicenseStatus: This API is used to read license status ```objectivec +(NSString*)getLicenseStatus; +(BOOL)allowsLiveness; +(NSString*)lastLicenseError; ``` #### detectImage: This API is used to detect faces and determine if the faces are real or fake ```objectivec +(NSString*)detectImage:(UIImage*)image crop:(BOOL)crop flags:(int)flags; ``` | **Input** |
  • image (UIImage\*): The input image
| | ---------------- | --------------------------------------------------------------------- | | **Return value** | JSON string with detected faces and liveness scores. | The liveness score ranges from 0.0 to 1.0. If it's greater than the threshold, it's real face. Demo default threshold is **0.5**. #### VideoWorker: This API is used for the live camera HUD ```objectivec +(int)startVideoWorkerWithMatchThreshold:(float)threshold; +(int)addVideoWorkerFrame:(UIImage*)image; +(int)addVideoWorkerSampleBuffer:(CMSampleBufferRef)sampleBuffer; +(void)stopVideoWorker; ``` The liveness demo does **not** enroll a match database. #### deinitSDK: This API is used to unload the engine ```objectivec +(int)deinitSDK; ``` ### Run the demo 1. Place `facelivenessdk`, `FaceLivenessEngine`, and `onnxruntime` frameworks (see Setup). 2. Keep the Xcode bundle id **`com.faceplugin.faceliveness.app`**. 3. Run on a **physical** iPhone. Home tiles: **Liveness**, Settings, About. The demo does **not** enroll a match database. ### Screenshots Sample demo UI from `faceplugin-assets` (`face-liveness/mobile/`). Not a dedicated iOS photoshoot. | Home | Liveness | Settings | About | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Face Liveness sample demo home (mobile UI from faceplugin-assets, not a dedicated iOS photoshoot) | Faceplugin Face Liveness live camera | Faceplugin Face Liveness settings | Faceplugin Face Liveness About | Score **≥ 0.5** → real. Call `setActivation` → `initSDK` off the main thread. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Passive or active?** **Passive** anti-spoofing on this product. **Screenshots?** Sample demo UI from `faceplugin-assets` (`face-liveness/mobile/`). Not a dedicated iOS photoshoot. ### Related documentation * [Faceplugin Face Liveness Detection Mobile SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk) · [Android](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-android-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition iOS SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ios-sdk) * [ID Document Recognition iOS SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ios-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Server Faceplugin Face Liveness API for Windows and Linux Docker. On-premise anti-spoofing HTTP POST /api/liveness on port 8084. Score 0.5 or higher is Real. Score **one RGB JPEG** over HTTP. `POST /api/liveness` (alias `/api/check_liveness`). Score **0.5 or higher** → Real / pass. Typical call order: `GET /api/machinecode` → send machine code → `POST /api/activate` → `POST /api/liveness`. Default port **8084**. For a live camera on Android or iOS, use [Mobile SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk). Need recognition **and** liveness? Run [Face Recognition Linux](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) on port **8083** and this product on port **8084**. Do not mix their `lib/cpu` runtimes.
Linux SDKDocker image faceplugin/face-liveness. Same HTTP API as Windows.linux-docker.pngLinux
Windows SDKHTTP API on port 8084. Send a JPEG, get a liveness score. No Docker.windows.pngWindows
```mermaid flowchart LR JPEG --> PAD PAD --> Score Score --> RealOrSpoof ``` ### FAQ **What is the Face Liveness API?** `POST /api/liveness` on port **8084**. Score **≥ 0.5** is Real / pass. **Is this document anti-spoofing?** No. Use [ID Document Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk). ### Related documentation * [Capabilities](https://github.com/gentlebear0988/temp-docs/tree/main/faceplugin-docs/liveness-detection-sdk/capabilities.md) · [Faceplugin Face Liveness Detection Mobile SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk) · [Face Liveness Detection SDK](/products/face-recognition-sdk/liveness-detection-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) * [ID Document Liveness Server SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Linux Faceplugin Face Liveness API for Linux Docker. On-premise anti-spoofing PAD. POST /api/liveness on port 8084. Score 0.5 or higher is Real. Fully on-premise **Face Liveness HTTP API for Linux / Docker**. Image: `faceplugin/face-liveness`. Default port **8084**. Score **one RGB JPEG**. Score **≥ 0.5** → Real / `pass` true. Score **< 0.5** → Spoof / `pass` false. Need recognition as well? Run [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) on port **8083** as a **second** container. All processing stays on your server. **No** biometric data is sent to Faceplugin cloud. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Pull from Docker Hub (no Google Drive download) ``` 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 ``` On Docker Desktop (macOS/Windows) omit the `/etc/machine-id` volume. {% endstep %} {% step %} ## Confirm health (no license yet) ``` curl -s http://127.0.0.1:8084/api/health ``` {% endstep %} {% step %} ## Copy the machine code ``` curl -s http://127.0.0.1:8084/api/machinecode ``` Send machine code to Faceplugin. Docker and local host codes are **different**. {% endstep %} {% step %} ## Activate Put your key in `license.txt`, then: ``` curl -s -X POST http://127.0.0.1:8084/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% step %} ## Check liveness ``` IMG=$(base64 -w0 face.jpg) # macOS: base64 -i face.jpg curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` {% endstep %} {% endstepper %} ### Run multiple containers with one license You only need this section if you want to run multiple Face 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: ```bash sudo docker run -d --name faceplugin-face-liveness-2 \ --shm-size=1gb --privileged \ -p 8085:8084 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/face-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/FaceLivenessDetection-Docker.git cd FaceLivenessDetection-Docker ``` Put the [Google Drive runtime](https://drive.google.com/drive/folders/1rFnw7VASLmA4q8NWenQgszFS8njRGEgt) 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 ``` Default port **8084**. Gradio demo (`demo.py`) on **9004** (host only). The Docker Hub image is API-only. `POST /api/check_liveness` is an alias of `/api/liveness`. {% hint style="info" %} Control routes (`/api/health`, `/api/machinecode`, `/api/activate`, `/api/licenseStatus`) return a JSON **envelope**. `POST /api/liveness` returns **engine JSON** as the HTTP body. {% endhint %} ### License Licenses are **offline**. [Request a License & Support](/help/request-a-license-and-support). ### 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/liveness` | Passive face anti-spoofing | | `POST /api/check_liveness` | Alias of `/api/liveness` | Full reference: [Face Liveness HTTP API](/integration/http-api/face-liveness). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). `POST /api/liveness` returns **engine JSON** as the body. Score **≥ 0.5** → Real / `pass` true. Python: ```python import sdk machine_code = sdk.get_machine_code() sdk.activate("license.txt") sdk.init_sdk() print(sdk.liveness(base64_jpeg)) ``` ### Try it ```bash curl -s http://127.0.0.1:8084/api/health IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` **Postman:** import `postman/FaceLiveness-API.postman_collection.json` from the repo. Base URL `http://127.0.0.1:8084`. **Gradio (host only):** ``` pip3 install -r requirements-demo.txt DEMO_PORT=9004 API_BASE=http://127.0.0.1:8084 python3 demo.py ``` Open . You do **not** need Gradio in production. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Face Liveness API?** `POST /api/liveness` on port **8084**. Score **≥ 0.5** → Real. **Machine code?** `GET /api/machinecode` returns machine code. Docker and host codes differ. ### Related documentation * [Faceplugin Face Liveness Detection Server SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk) · [Windows](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) * [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) * [ID Document Liveness Linux SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Windows Faceplugin Face Liveness Detection Windows SDK. Fully on-premise PAD HTTP API on port 8084. POST /api/liveness. No Docker. Fully on-premise **Face Liveness HTTP API for Windows**. Default port **8084**. Gradio **9004**. No Docker on Windows. Score **one RGB JPEG**. Score **≥ 0.5** → Real / `pass` true. Same HTTP API as [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk). `POST /api/check_liveness` is an alias of `/api/liveness`. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Copy the runtime Copy the CPU libraries from [Google Drive](https://drive.google.com/drive/folders/11xD987eHT00NUGiJZCNYSvwRadi0Nue5) into `lib\cpu\`. {% endstep %} {% step %} ## Install and run ``` pip install -r requirements.txt run.bat ``` {% endstep %} {% step %} ## Copy the machine code ``` curl -s http://127.0.0.1:8084/api/machinecode ``` Send machine code to Faceplugin. {% endstep %} {% step %} ## Activate, then check liveness ``` curl -s -X POST http://127.0.0.1:8084/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` {% endstep %} {% endstepper %} ### 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/liveness` | Passive face anti-spoofing | | `POST /api/check_liveness` | Alias of `/api/liveness` | Full reference: [Face Liveness HTTP API](/integration/http-api/face-liveness). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). `POST /api/liveness` returns **engine JSON** as the body. Score **≥ 0.5** → Real / `pass` true. Python: ```python import sdk sdk.get_machine_code() sdk.activate("license.txt") sdk.init_sdk() print(sdk.liveness(base64_jpeg)) ``` ### Try it ```bash curl -s http://127.0.0.1:8084/api/health IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` **Postman:** import `postman/FaceLiveness-API.postman_collection.json` from the repo. Base URL `http://127.0.0.1:8084`. **Gradio (host only):** `DEMO_PORT=9004 API_BASE=http://127.0.0.1:8084 python demo.py`. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **API?** Same as Linux: `POST /api/liveness` on port **8084**. No Docker on Windows. **Active liveness?** No. This product is passive JPEG anti-spoofing only. ### Related documentation * [Faceplugin Face Liveness Detection Server SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk) · [Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) * [ID Document Recognition Windows SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-windows-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Recognition + Liveness Faceplugin Face SDK — Recognition + Liveness. Mobile Identify with 2D liveness, and server combined API on port 8083 with /api/liveness. Products that ship **face recognition and liveness together**. ### Mobile On-device enroll / **1:N Identify** with **passive 2D liveness** (same native engine as FaceRecognitionSDK Android / iOS). See [Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk). ### Server One process on port **8083**: recognition routes **plus** `POST /api/liveness`. Image: `faceplugin/face-recognition-liveness-sdk`. See [Server](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server) for Linux, Windows, and .NET. **Capabilities:** [Face SDK capabilities](/products/face-recognition-sdk/capabilities). Prefer two separate server products? Run [Recognition](/products/face-recognition-sdk/recognition) on **8083** and [Liveness](/products/face-recognition-sdk/liveness-detection-sdk) on **8084**. For production eKYC, prefer this combined Face package — see [Deploy and host](/integration/deploy-and-host/architecture). # Mobile Faceplugin Face Recognition Mobile SDK. On-premise 1:1 and 1:N matching for Android, iOS, Flutter, React Native, and Ionic. Offline setActivation, init, VideoWorker Identify. On-device **Face Recognition + Liveness** for Android, iOS, Flutter, React Native, and Ionic. Enroll people, run live **1:N Identify** with **passive 2D liveness**, and store templates in **your** database. Processing stays on the phone. These apps wrap the same native FaceRecognitionSDK engines (recognition + liveness). They are **not** under Recognition-only. Server combined HTTP API: [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness). Recognition-only server (no `/api/liveness`): [Recognition](/products/face-recognition-sdk/recognition) / [Server SDK](/products/face-recognition-sdk/recognition/server-sdk). Typical call order: `setActivation` → `init` → detect / extract template → `similarity` or VideoWorker (live 1:N). Identify default **0.67**. Liveness default **0.5**.
Android SDKNative AAR. Enroll, Identify, Capture, and Attribute screens.android.pngAndroid
iOS SDKXcode frameworks. Same demo screens as Android.apple-logo-3-300x300.pngiOS
Flutter SDKface_recognition_sdk plugin plus an example app.flutter.pngFlutter
React Native SDKface-recognition-sdk plugin. Yarn 3, not Expo Go.react.pngReact Native
Ionic Capacitor SDKface-recognition-capacitor for new Ionic apps.ionic.pngIonic Capacitor
Ionic Cordova SDKLegacy Cordova plugin. Prefer Capacitor for new projects.cordova.pngIonic Cordova
```mermaid flowchart LR Camera --> Detect Detect --> Liveness2D Liveness2D --> Embedding Embedding --> Identify Identify --> Result ``` ### Related documentation * [Capabilities](/products/face-recognition-sdk/capabilities) · [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) · [Face SDK](/products/face-recognition-sdk) · [Glossary](/help/resources/glossary) * [Standalone Face Liveness Mobile SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Android Faceplugin Face Recognition Android SDK. Fully on-premise face matching, 1:N identify, and 2D liveness. AAR, setActivation, init, faceDetection, VideoWorker. Fully on-premise **Face Recognition SDK for Android**. Detect faces, extract templates you store yourself, match 1:1 or live 1:N, and check passive 2D liveness on the device. Images never leave the phone. Public class: `com.faceplugin.facerecognitionsdk.FaceRecognitionSDK`. Demo tiles: Enroll, Identify, Capture, Attribute, Settings, About. ### Code {% embed url="" %} ### Setup 1. Copy the SDK (`libfacesdk` folder) to the `root` folder in your project. Place `facerecognitionsdk.aar` from [Google Drive](https://drive.google.com/drive/folders/1kpzYVv9Gbm_pEpDe9-x7FGB4NWZzvez0) inside `libfacesdk/` (next to `libfacesdk/build.gradle`). 2. Add SDK to the project in `settings.gradle` ``` rootProject.name = "YourProjectName" include ':app' include ':libfacesdk' ``` 3. Add dependency to your `app/build.gradle` ``` android { defaultConfig { minSdk 24 ndk { abiFilters 'arm64-v8a', 'armeabi-v7a' } } packaging { jniLibs { useLegacyPackaging = true } } } dependencies { implementation project(path: ':libfacesdk') } ``` 4. Add camera / gallery permissions in `AndroidManifest.xml`. Call **setActivation → init** on a **background** thread. Keep the demo package name **`com.faceplugin.facerecognitionsdk`**. Request a new license key for your own app. {% hint style="info" %} Serialize native calls on one thread. The engine is not concurrent. First `init` unpacks on-device models (a few seconds). {% endhint %} Status codes: **0** Success (`SDK_SUCCESS`), **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ### APIs #### setActivation: This API is used to activate the SDK ```java public static int setActivation(Context context, String license); ``` | **Input** |
  • context (Context): Android Context
  • license (String): The license string (license key)
| | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** |

The SDK activation status code.

  • 0: Success
  • 1: Invalid license
  • 2: Expired
  • 3: Not activated
  • 4: Init failed
| #### init: This API is used to initialize the SDK ```java public static int init(Context context) throws IOException; ``` | **Input** |
  • context (Context): Android Context
| | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | **Return value** |

The SDK initialization status code.

  • 0: Success
  • 1–4: see setActivation
| #### getMachineCode: This API is used to retrieve the machine code ```java public static String getMachineCode(Context context); ``` | **Input** |
  • context (Context): Android Context
| | ---------------- | ---------------------------------------------------------------------------------- | | **Return value** | Machine code string (for license requests). | #### getLicenseStatus: This API is used to read license status ```java public static String getLicenseStatus(); public static boolean allowsRecognition(); public static boolean allowsLiveness(); public static String lastLicenseError(); public static boolean isActivated(); ``` | **Input** | None | | ---------------- | ------------------- | | **Return value** | JSON status string. | #### faceDetection: This API is used to detect faces ```java public static List faceDetection(Bitmap bitmap, FaceDetectionParam param); ``` | **Input** |
  • bitmap (Bitmap): The Bitmap image
  • param (FaceDetectionParam): Parameters for face detection
| | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Return value** | A list of **FaceBox** objects representing the detected faces. | **FaceDetectionParam** ```java public class FaceDetectionParam { public boolean check_liveness = false; public int check_liveness_level = 0; // 0: High Accuracy, 1: Light public boolean check_eye_closeness = false; public boolean check_face_occlusion = false; public boolean estimate_age_gender = false; public boolean check_pose = true; public boolean check_landmarks = true; public boolean check_quality = false; public boolean check_emotion = false; public boolean check_mask = false; public boolean check_glasses = false; } ``` Use `FaceDetectionParam.allAttributes()` when you want liveness, age, gender, emotion, and quality in one call. **FaceBox** ```java public class FaceBox { public int x1, y1, x2, y2; public float yaw, roll, pitch, liveness; public float face_quality, face_luminance; public float left_eye_closed, right_eye_closed, face_occlusion, mouth_opened; public int age, gender, landmarkCount; public float[] landmarks_68; public String livenessLabel, genderLabel, emotionLabel, maskLabel; public String qualityLabel, eyesLeftLabel, eyesRightLabel, rawJson; } ``` The liveness score ranges from **0.0** to **1.0**. If it is greater than the threshold, it is a real face. Demo default threshold is **0.5**. #### templateExtraction: This API is used to extract face template ```java public static byte[] templateExtraction(Bitmap bitmap, FaceBox faceBox); ``` | **Input** |
  • bitmap (Bitmap): The Bitmap image
  • faceBox (FaceBox): The bounding box of the detected face
| | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** | A byte array representing the extracted template from the face. Store these in **your** database. | #### similarityCalculation: This API is used to calculate the similarity between two face templates ```java public static float similarityCalculation(byte[] feature1, byte[] feature2); ``` | **Input** |
  • feature1 (byte\[]): The first face template
  • feature2 (byte\[]): The second face template
| | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** | A float similarity score. Demo Identify default threshold is **0.67**. | `similarity(byte[] feature1, byte[] feature2)` is an alias of `similarityCalculation`. #### detect: This API is used to detect faces and return engine JSON ```java public static String detect(Bitmap bitmap, boolean crop); public static String detect(Bitmap bitmap, boolean crop, int flags); ``` | **Input** |
  • bitmap (Bitmap): The Bitmap image
  • crop (boolean): Whether to crop faces
  • flags (int): Bit flags (DETECT\_ALL, DETECT\_LANDMARKS, DETECT\_LIVENESS, DETECT\_LIVENESS\_ACCURATE, …)
| | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** | JSON string (same idea as HTTP `POST /api/detect`). | #### quality: This API is used to run face image quality checks ```java public static String quality(Bitmap bitmap, boolean crop); ``` #### match: This API is used to compare two photos (1:1) ```java public static String match(Bitmap image1, Bitmap image2, boolean crop); ``` #### extractFeature: This API is used to extract a template from a cropped face image ```java public static String extractFeature(Bitmap bitmap); ``` Also: `cropFace(Bitmap, FaceBox)`, `parseFeatureBytes(String json)`, `yuv2Bitmap(...)`, `estimatorStatusJSON()`. #### setLandmarkMode: This API is used to set the landmark model ```java public static int setLandmarkMode(int mode); // 14, 68, or 468 public static int getLandmarkMode(); ``` #### VideoWorker: This API is used for live 1:N identify Call in this order: `startVideoWorker` → `syncVideoWorkerDatabase(templates)` → `addVideoWorkerFrame` → `stopVideoWorker`. Listen with `setVideoWorkerEventHandler`. Identify in the demo is **passive 2D** liveness plus VideoWorker. ```java FaceRecognitionSDK.startVideoWorker(config); FaceRecognitionSDK.syncVideoWorkerDatabase(templates, 0.67f); FaceRecognitionSDK.addVideoWorkerFrame(bitmap); FaceRecognitionSDK.stopVideoWorker(); ``` Also: `startVideoWorker(float matchThreshold)`, `addVideoWorkerFrameRgb`, `addVideoWorkerFrameBgra`, `VideoWorkerConfig` / `ActiveLivenessConfig`. | **Input** | Match threshold, enrolled templates, and camera frames. | | ---------------- | ------------------------------------------------------- | | **Return value** | Match events via the VideoWorker listener (JSON). | #### deinit: This API is used to unload the engine ```java public static int deinit(); ``` | **Input** | None | | ---------------- | ---------------------------- | | **Return value** | Status code. **0**: Success. | ### Run the demo 1. Place `facerecognitionsdk.aar` in `libfacesdk/` (see Setup). 2. Open the cloned repo in Android Studio. 3. Run on a **physical** phone (emulator is not recommended for camera / liveness). 4. Wait until the home status bar disappears. Then **Enroll / Identify / Capture / Attribute** unlock. Keep the demo package name **`com.faceplugin.facerecognitionsdk`** so the sample key works. | Demo tile | What it does | | ------------- | ----------------------------------------------------------------------------------- | | **Enroll** | Enroll a person from a gallery photo (exactly one face) into the on-device database | | **Identify** | Live 1:N camera match (stop on first hit) with 2D liveness | | **Capture** | Oval coach capture → still with attributes → optional enroll | | **Attribute** | Gallery analysis: landmarks, liveness, pose, quality, age, gender, emotion | | **Settings** | Camera lens, identify / liveness / pose / eye-close thresholds | | **About** | SDK name and license label | ### Screenshots | Home | Identify | Capture | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Face Recognition Android home | Faceplugin Face Recognition live identify | Faceplugin Face Recognition oval capture | ### System requirements | Item | Minimum | Recommended | | ------- | -------------------------- | -------------------- | | Android | API 24 (7.0) | API 29 (10) or newer | | ABI | `arm64-v8a`, `armeabi-v7a` | `arm64-v8a` | | RAM | 4 GB | 6 GB or more | | Camera | Front camera | 720p or 1080p | | Device | Physical device | Same | ### License Licenses are **offline**. Keep the demo package name so the sample key works. For your own app, [request a license](/help/request-a-license-and-support). ### Try it (after the demo compiles) ```kotlin Thread { FaceRecognitionSDK.getMachineCode(context) var code = FaceRecognitionSDK.setActivation(context, DEMO_LICENSE) if (code == FaceRecognitionSDK.SDK_SUCCESS) { code = FaceRecognitionSDK.init(context) } val faces = FaceRecognitionSDK.faceDetection(bitmap, FaceDetectionParam()) if (faces.isNotEmpty()) { val t = FaceRecognitionSDK.templateExtraction(bitmap, faces[0]) val score = FaceRecognitionSDK.similarityCalculation(t, t) } }.start() ``` {% hint style="warning" %} Call `setActivation`, `init`, and all process methods **off the UI thread**. The engine is **not** concurrent — serialize calls on one thread. {% endhint %} ### Integrate into your own app You need `libfacesdk/` (the AAR) and `FaceRecognitionSDK`. You do **not** need the demo Activities. 1. Copy `libfacesdk` into your project root and put `facerecognitionsdk.aar` inside it. 2. Wire Gradle as in Setup (`minSdk 24`, `abiFilters`, `useLegacyPackaging`). 3. Add CAMERA and photo-library permissions. 4. Request license key for your own app. 5. Optional: copy `app/.../kit/` (`FaceRecognitionClient`) so you do not rewrite threading, CameraX, or VideoWorker. Typical call order: `setActivation` → `init` → `faceDetection` → `templateExtraction` → store templates in **your** database → `similarityCalculation` or VideoWorker for live 1:N. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **What APIs does this page ship?** Java/Kotlin `FaceRecognitionSDK.setActivation`, `init`, `faceDetection`, `templateExtraction`, `similarityCalculation`, and VideoWorker Identify. **Offline / on-premise?** Yes, after a license key bound to the demo app id (or your own id). **Identify threshold?** Default **0.67**. Mobile Identify includes **passive 2D liveness**. ### Related documentation * [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [iOS](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ios-sdk) · [Glossary](/help/resources/glossary) * [Face Liveness Detection Android SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-android-sdk) * [ID Document Recognition Android SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-android-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # iOS Faceplugin Face Recognition iOS SDK. Fully on-premise face matching, 1:N identify, and 2D liveness. Xcode frameworks, setActivation, initSDK, detectImage, VideoWorker. Fully on-premise **Face Recognition SDK for iOS**. Detect faces, extract templates, match 1:1 or live 1:N, and check passive 2D liveness on the device. Native class: `FaceRecognitionSDK` (`facerecognitionsdk.framework`). Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ### Code {% embed url="" %} ### Setup 1. Unzip the frameworks from [Google Drive](https://drive.google.com/drive/folders/1PKmV-o7gq7s7dDtiNgXPfCi2ZlWaRy5H) next to the Xcode project: `facerecognitionsdk.framework`, `FaceRecognitionEngine.framework`, `onnxruntime.framework`. 2. Add the SDK frameworks to the project in Xcode (**Embed & Sign**). 3. Add `FaceRecognitionSDK-Bridging-Header.h` to Build Settings (`#import `). 4. Set **your** Signing Team. Demo bundle id: **`com.faceplugin.facerecognitionsdk.app`**. Physical iPhone, iOS 13+. Call **setActivation → initSDK** off the main thread. ### APIs #### setActivation: This API is used to activate the SDK ```objectivec +(int)setActivation:(NSString*)license; ``` | **Input** |
  • license (NSString\*): The license string (license key)
| | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** |

The SDK activation status code.

  • 0: Success
  • 1: Invalid license
  • 2: Expired
  • 3: Not activated
  • 4: Init failed
| #### initSDK: This API is used to initialize the SDK ```objectivec +(int)initSDK; ``` | **Input** | None | | ---------------- | ------------------------------------------------------------------------------------------------------------------ | | **Return value** |

The SDK initialization status code.

  • 0: Success
  • 1–4: see setActivation
| #### getMachineCode: This API is used to retrieve the machine code ```objectivec +(NSString*)getMachineCode; ``` #### getLicenseStatus: This API is used to read license status ```objectivec +(NSString*)getLicenseStatus; +(BOOL)allowsRecognition; +(BOOL)allowsLiveness; +(NSString*)lastLicenseError; +(BOOL)isActivated; ``` #### detectImage: This API is used to detect faces and return engine JSON ```objectivec +(NSString*)detectImage:(UIImage*)image crop:(BOOL)crop; +(NSString*)detectImage:(UIImage*)image crop:(BOOL)crop flags:(FaceRecognitionDetectFlags)flags; ``` | **Input** |
  • image (UIImage\*): The input image
  • flags: Estimators to run (FaceRecognitionDetectAll, DetectLiveness, …)
| | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Return value** | JSON string (Linux-compatible, same idea as HTTP `POST /api/detect`). | #### qualityImage: This API is used to run face image quality checks ```objectivec +(NSString*)qualityImage:(UIImage*)image crop:(BOOL)crop; ``` #### matchImage1: This API is used to compare two photos (1:1) ```objectivec +(NSString*)matchImage1:(UIImage*)image1 image2:(UIImage*)image2 crop:(BOOL)crop; ``` #### extractFeatureFromImage: This API is used to extract a face template ```objectivec +(NSString*)extractFeatureFromImage:(UIImage*)image; ``` | **Input** | A face image (typically cropped). | | ---------------- | --------------------------------------------------------------------- | | **Return value** | JSON with the template. Store the feature bytes in **your** database. | #### similarityWithFeature1: This API is used to calculate the similarity between two face templates ```objectivec +(float)similarityWithFeature1:(NSData*)feature1 feature2:(NSData*)feature2; ``` | **Input** | Two template blobs from `extractFeatureFromImage`. | | ---------------- | ---------------------------------------------------------------------------------------- | | **Return value** | Similarity **0.0–1.0**, or **-1** on error. Demo Identify default threshold is **0.67**. | #### setLandmarkMode: This API is used to set the landmark model ```objectivec +(int)setLandmarkMode:(int)mode; // 14, 68, or 468 +(int)landmarkMode; ``` #### VideoWorker: This API is used for live 1:N identify ```objectivec +(int)startVideoWorkerWithMatchThreshold:(float)threshold; +(int)startVideoWorkerWithConfig:(FaceRecognitionVideoWorkerConfig*)config; +(int)syncVideoWorkerDatabaseWithFeatures:(NSArray*)features matchThreshold:(float)threshold; +(int)addVideoWorkerFrame:(UIImage*)image; +(int)addVideoWorkerSampleBuffer:(CMSampleBufferRef)sampleBuffer; +(NSString*)extractFeatureWithSampleBuffer:(CMSampleBufferRef)sampleBuffer; +(void)setVideoWorkerEventHandler:(void(^)(NSString* json))handler; +(void)stopVideoWorker; ``` #### deinitSDK: This API is used to unload the engine ```objectivec +(int)deinitSDK; ``` ### Run the demo 1. Place the three frameworks next to the Xcode project (see Setup). 2. Keep demo bundle id **`com.faceplugin.facerecognitionsdk.app`**. 3. Run on a **physical** iPhone (iOS 13+). 4. Wait until the home status bar shows Ready. Then Enroll / Identify / Capture / Attribute unlock. Call **setActivation → initSDK** off the main thread. The engine is **not** concurrent. ### Screenshots The gallery is **Android** sample UI from `faceplugin-assets`. iOS demo tiles match these screens; there is no separate iOS photoshoot in these docs. | Home | Identify | Capture | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Face Recognition Android sample UI (shown on the iOS page; no separate iOS screenshot yet) | Faceplugin Face Recognition live identify | Faceplugin Face Recognition oval capture | ### License Licenses are **offline**. The sample key is only for the demo bundle. Request a new license key if you change the demo bundle. Identify default threshold is **0.67**. Liveness demo default is **0.5**. ### Integrate into your own app You need the three frameworks and `FaceRecognitionSDK`. You do **not** need the demo view controllers. Typical call order: `setActivation` → `initSDK` → `detectImage` / `extractFeatureFromImage` → store templates in **your** database → `similarityWithFeature1:feature2:` or VideoWorker for live 1:N. Public header only: `detectImage`, `extractFeatureFromImage`, `similarityWithFeature1:feature2:`, VideoWorker. There is **no** Objective-C `faceDetection:` returning `FaceBox` on this framework. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **What APIs does this page ship?** Swift equivalents of `setActivation`, `init`, face detection, template extract, similarity, and VideoWorker Identify. **Are the screenshots iOS?** No. The gallery uses **Android** sample UI. iOS demo tiles match those screens. **Offline?** Yes, after license key for the demo bundle id (or yours). ### Related documentation * [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Android](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) · [Glossary](/help/resources/glossary) * [Face Liveness Detection iOS SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-ios-sdk) * [ID Document Recognition iOS SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ios-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Flutter Faceplugin Face Recognition Flutter SDK. On-premise 1:1 and 1:N matching with 2D liveness. face\_recognition\_sdk plugin for Android and iOS. Fully on-premise **Face Recognition SDK for Flutter**. Package: `face_recognition_sdk`. Same native engines as the Android and iOS Face Recognition SDKs. All processing stays on the device. **No** biometric data is sent to Faceplugin cloud. ### Code {% embed url="" %} ### How to Run {% stepper %} {% step %} ## Install tools Flutter **3.44+** and Dart **3.3+** (from the package `pubspec.yaml`), JDK **17+** for Android. Run `flutter doctor` and fix reported issues. Accept Android licenses: `flutter doctor --android-licenses`. `JAVA_HOME` must point to the JDK **home** (the folder that contains `bin`), not to `bin` itself. {% endstep %} {% step %} ## Clone and bootstrap ```bash git clone https://github.com/Faceplugin-ltd/FaceRecognition-Flutter.git cd FaceRecognition-Flutter dart run tool/bootstrap.dart ``` {% endstep %} {% step %} ## Place native runtimes | Platform | File | Example app path | Your own app path | | -------- | ------------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------- | | Android | `facerecognitionsdk.aar` | `example/android/libfacesdk/` | Copy `example/android/libfacesdk/` into **your app** `android/libfacesdk/` and `include(":libfacesdk")` | | iOS | three frameworks | `ios/Frameworks/` | Plugin checkout `ios/Frameworks/` | * Android Google Drive: [facerecognitionsdk.aar](https://drive.google.com/drive/folders/1kpzYVv9Gbm_pEpDe9-x7FGB4NWZzvez0) * iOS Google Drive: [frameworks](https://drive.google.com/drive/folders/1PKmV-o7gq7s7dDtiNgXPfCi2ZlWaRy5H) (`facerecognitionsdk`, `FaceRecognitionEngine`, `onnxruntime`) {% hint style="warning" %} Do **not** `implementation(files(…aar))` inside the plugin — AGP will fail `bundleDebugAar`. Copy the `libfacesdk` **module** from the example into your app. {% endhint %} On a Mac after placing iOS frameworks: `dart run tool/bootstrap.dart` (builds matching `.xcframework`s) then `cd example/ios && pod install`. CocoaPods links the `.xcframework`s into the plugin pod — plain `.framework` alone often leaves undefined `FaceRecognitionSDK` symbols under `use_frameworks!`. {% endstep %} {% step %} ## Run the example ```bash cd example flutter run ``` Physical phone. Wait for the home status bar → **Ready**. {% endstep %} {% endstepper %} Keep demo ids so the included license works: | Platform | Id | | --------------------- | ------------------------------------ | | Android package name | `com.faceplugin.facerecognitionsdk` | | iOS bundle identifier | `com.faceplugin.facerecognition.app` | | Requirement | Value | | ----------- | -------------------------------------- | | Flutter | 3.44+ (see `pubspec.yaml`) | | Android | minSdk 24, physical device recommended | | iOS | iOS 13+, physical device recommended | Demo tiles: Enroll, Identify, Capture, Attribute, Settings, About. ### Screenshots The gallery is **Android** sample UI from `faceplugin-assets`. The Flutter plugin wraps the same native engines; there is no separate Flutter photoshoot in these docs. | Home | Identify | Capture | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Face Recognition Android sample UI (shown on the Flutter page; no separate Flutter screenshot yet) | Faceplugin Face Recognition live identify | Faceplugin Face Recognition oval capture | ### License Licenses are **offline**. Demo keys live in `example/lib/core/constants/license.dart`. Request a new license key for your own app. Default thresholds in the example Settings: identify **0.67**, liveness **0.5**, pose **40°**, eye-close **0.5**. You pass these as Dart parameters — change them for your product. [Request a License & Support](/help/request-a-license-and-support). ### Integrate into your own app You need the Flutter plugin + native runtimes. You do **not** need the example UI or person database. ```yaml dependencies: face_recognition_sdk: git: url: https://github.com/Faceplugin-ltd/FaceRecognition-Flutter.git ``` Then copy runtimes (table above), set your Android package name / iOS bundle identifier, add camera + photo-library permissions, and request a license for your own app. ```dart import 'package:face_recognition_sdk/face_recognition_sdk.dart'; Future activate() async { final code = await getMachineCode(); // machine code — send when requesting a key final act = await setActivation('license key'); if (act != sdkSuccess) { throw StateError(await lastLicenseError()); } final initCode = await init(); if (initCode != sdkSuccess) { throw StateError('init failed: $initCode'); } } Future enrollStill(String imagePath) async { final faces = await faceDetection(imagePath); if (faces.length != 1) return; final template = await templateExtraction(imagePath, faces.first); final cropB64 = await cropFace(imagePath, faces.first); // Store template + crop in YOUR database } ``` Optional oval UI: `FaceCapture` from `package:face_recognition_sdk/capture`. ### APIs ```dart import 'package:face_recognition_sdk/face_recognition_sdk.dart'; ``` Call order: `getMachineCode` → `setActivation` → `init` → detect / VideoWorker → `deinit`. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. #### setActivation: This API is used to activate the SDK ```dart Future setActivation(String license) ``` #### init: This API is used to initialize the SDK ```dart Future init() ``` #### getMachineCode: This API is used to retrieve the machine code ```dart Future getMachineCode() ``` #### faceDetection: This API is used to detect faces ```dart Future> faceDetection(String imageUri, [FaceDetectionParam param]) ``` Boxes include geometry (`x1,y1,x2,y2`), pose, liveness / quality / eyes / occlusion, age / gender / emotion / mask / glasses, optional `attributes`, and `landmarks` + `landmarkCount`. #### templateExtraction: This API is used to extract face template ```dart Future templateExtraction(String imageUri, FaceBox faceBox) ``` #### similarity: This API is used to calculate similarity between two templates ```dart Future similarity(String feature1B64, String feature2B64) ``` #### detect: This API is used to detect faces and return engine JSON ```dart Future detect(ImageInput image, {bool crop = false, int flags = DETECT_ALL}) ``` Also: `extractFeature`, `quality`, `cropFace`, `setLandmarkMode` / `getLandmarkMode`, `getLicenseStatus`, `lastLicenseError`, `deinit`. #### VideoWorker: This API is used for live 1:N identify ```dart Future startVideoWorker(VideoWorkerConfig config) Future syncVideoWorkerDatabase(List features, {double matchThreshold = 0.67}) Future ingestLiveCameraFrame(LiveCameraPhoto photo, LiveFrameOptions options) Stream get videoWorkerEvents Future stopVideoWorker() ``` [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Package?** `face_recognition_sdk`. **Screenshots?** The gallery uses **Android** sample UI. The plugin wraps native Android and iOS engines. **Face Liveness Flutter SDK?** None public. ### Related documentation * [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [React Native](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-react-native-sdk) · [Glossary](/help/resources/glossary) * [ID Document Recognition Flutter SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-flutter-sdk) * There is no public Face Liveness Flutter SDK — use Identify 2D liveness or native Android/iOS Liveness. * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # React Native Faceplugin Face Recognition React Native SDK. On-premise 1:1 and 1:N matching with 2D liveness. face-recognition-sdk plugin, Yarn 3, not Expo Go. Fully on-premise **Face Recognition SDK for React Native** (Android and iOS). Package: `face-recognition-sdk`. It wraps the same native engines as the Android and iOS Face Recognition SDKs. All processing stays on the device. **No** biometric data is sent to Faceplugin cloud. {% hint style="warning" %} **Expo Go is not supported.** You need a development build (bare React Native or Expo prebuild) because this package includes native Android / iOS code. Use **Yarn 3** as in `package.json` (do not `npm install` at the repo root). {% endhint %} ### Code {% embed url="" %} ### How to Run {% stepper %} {% step %} ## Install tools Node **18+**, Yarn, and a React Native environment ([setup guide](https://reactnative.dev/docs/environment-setup)). Physical phone recommended (emulator is limited for camera / liveness). {% endstep %} {% step %} ## Clone and install ```bash git clone https://github.com/Faceplugin-ltd/FaceRecognition-React-Native.git cd FaceRecognition-React-Native yarn cd example && yarn ``` {% endstep %} {% step %} ## Place native runtimes Native binaries are **not** on GitHub (too large). | Platform | File | Example app path | Your own app path | | -------- | ------------------------ | ----------------------------- | --------------------------------------------------- | | Android | `facerecognitionsdk.aar` | `example/android/libfacesdk/` | `node_modules/face-recognition-sdk/android/libs/` | | iOS | three frameworks | `ios/Frameworks/` | `node_modules/face-recognition-sdk/ios/Frameworks/` | * Android Google Drive: [facerecognitionsdk.aar](https://drive.google.com/drive/folders/1kpzYVv9Gbm_pEpDe9-x7FGB4NWZzvez0) * iOS Google Drive: [frameworks](https://drive.google.com/drive/folders/1PKmV-o7gq7s7dDtiNgXPfCi2ZlWaRy5H) (`facerecognitionsdk`, `FaceRecognitionEngine`, `onnxruntime`) {% endstep %} {% step %} ## Run on a phone ```bash cd example yarn android ``` On macOS for iOS: ```bash cd example cd ios && pod install && cd .. yarn ios --device ``` Open `example/ios/FaceRecognitionSdkExample.xcworkspace` in Xcode if you prefer. Wait until the home status bar shows **Ready**. {% endstep %} {% endstepper %} Keep the demo package name **`com.faceplugin.facerecognitionsdk`** on Android and iOS so the sample key works. | Requirement | Value | | ------------ | ------------------------------------------ | | React Native | 0.74.x (example ships 0.74.5) | | Android | minSdk 24, physical device recommended | | iOS | iOS 13+, A12+ recommended, physical device | | Demo tile | What it does | | ------------- | ----------------------------------------------------------------------------------- | | **Enroll** | Enroll a person from a gallery photo (exactly one face) into the on-device database | | **Identify** | Live 1:N camera match (VideoWorker) with 2D liveness | | **Capture** | Oval coach capture → still with attributes → optional enroll | | **Attribute** | Gallery analysis: landmarks, liveness, pose, quality, age, gender, emotion | | **Settings** | Camera lens, identify / liveness / pose / eye-close thresholds | | **About** | SDK name and license label | ### Screenshots The gallery is **Android** sample UI from `faceplugin-assets`. The React Native plugin wraps the same native engines; there is no separate RN photoshoot in these docs. | Home | Identify | Capture | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Face Recognition Android sample UI (shown on the React Native page; no separate RN screenshot yet) | Faceplugin Face Recognition live identify | Faceplugin Face Recognition oval capture | ### License Licenses are **offline**. The sample key is only for the demo app. Request a new license key for your own app. Default thresholds in Settings: identify **0.67**, liveness **0.5**, pose **40°**, eye-close **0.5**. [Request a License & Support](/help/request-a-license-and-support). ### Integrate into your own app ```bash yarn add github:Faceplugin-ltd/FaceRecognition-React-Native ``` 1. Copy `facerecognitionsdk.aar` into `node_modules/face-recognition-sdk/android/libs/` 2. Copy the three iOS frameworks into `node_modules/face-recognition-sdk/ios/Frameworks/` and `pod install` 3. Call `setActivation` → `init` before detect / VideoWorker 4. For the optional oval UI (`FaceCapture`), also install peers: `react-native-vision-camera`, `react-native-svg`, plus camera permissions ```ts import { setActivation, init, faceDetection, templateExtraction, SDK_SUCCESS, } from 'face-recognition-sdk'; const code = await setActivation('license key'); if (code === SDK_SUCCESS) { await init(); } const faces = await faceDetection(uri, { allAttributes: true, check_liveness: true }); const probe = await templateExtraction(uri, faces[0]); const score = await similarity(probe, enrolledTemplateB64); ``` Live frames: pass `ingestLiveCameraFrame(photo, { frontCamera: true })` so Android and iOS share one orientation policy. Optional Capture UI: ```ts import { FaceCapture } from 'face-recognition-sdk/capture'; navigation.goBack()} onCaptured={(result) => { /* result.uri, result.faceBox, result.cropB64 */ }} /> ``` Person enrollment data in the example is **local** (`AsyncStorage`). Drive holds the **native runtime only**, not the enrolled gallery. ### APIs Call order: `getMachineCode` → `setActivation` → `init` → detect / VideoWorker → `deinit`. One TypeScript API for Android and iOS. Results use the **same FaceBox shape** on both platforms (Android is normalized for you). All methods return **Promises**. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ```ts import { setActivation, init, faceDetection, templateExtraction, similarity } from 'face-recognition-sdk'; ``` #### setActivation: This API is used to activate the SDK ```ts setActivation(license: string): Promise ``` #### init: This API is used to initialize the SDK ```ts init(): Promise ``` #### getMachineCode: This API is used to retrieve the machine code ```ts getMachineCode(): Promise ``` #### getLicenseStatus: This API is used to read license status ```ts getLicenseStatus(): Promise ``` #### faceDetection: This API is used to detect faces ```ts faceDetection(image: ImageInput, param?: FaceDetectionParam): Promise ``` `FaceBox` includes `x1,y1,x2,y2`, `liveness` / `livenessLabel`, age / gender / emotion, glasses / mask, `attributes`, and `landmarks`. Optional: `normalizeFaceBox` if you parse raw bridge JSON yourself. #### templateExtraction: This API is used to extract face template ```ts templateExtraction(image: ImageInput, faceBox: FaceBox): Promise ``` | **Input** | Image URI / path / base64, and a detected `FaceBox`. | | ---------------- | ---------------------------------------------------- | | **Return value** | Template as base64. Store it in **your** database. | #### similarity: This API is used to calculate similarity between two templates ```ts similarity(feature1: string, feature2: string): Promise ``` #### detect: This API is used to detect faces and return engine JSON ```ts detect(image: ImageInput, crop?: boolean, flags?: number): Promise ``` Also: `extractFeature`, `quality`, `cropFace`, `setLandmarkMode` / `getLandmarkMode` (`14` / `68` / `468`), `lastLicenseError`, `deinit`, `estimatorStatus`. #### VideoWorker: This API is used for live 1:N identify ```ts startVideoWorker(config?: VideoWorkerConfig): Promise syncVideoWorkerDatabase(featuresB64: string[], matchThreshold?: number): Promise ingestLiveCameraFrame(...): Promise subscribeVideoWorker(listener): () => void stopVideoWorker(): Promise ``` Prefer `ingestLiveCameraFrame` so rotation is handled for you. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Package?** `face-recognition-sdk`. Yarn 3; not Expo Go. **Screenshots?** The gallery uses **Android** sample UI. The plugin wraps native Android and iOS engines. **Liveness Flutter/React Native SDK?** None public. Identify includes 2D liveness. ### Related documentation * [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Flutter](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-flutter-sdk) · [Glossary](/help/resources/glossary) * [ID Document Recognition React Native SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-react-native-sdk) * There is no public Face Liveness React Native SDK — use Identify 2D liveness or native Android/iOS Liveness. * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Ionic Capacitor Faceplugin Face Recognition Ionic Capacitor SDK. On-premise face matching and liveness. face-recognition-capacitor plugin for new Ionic apps. Fully on-premise **Face Recognition SDK for Ionic Capacitor**. Package: `face-recognition-capacitor`. Use this for **new** Ionic apps. Cordova is a [different repo](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-cordova-sdk). `ionic serve` / the browser **cannot** load the engine. Open Android Studio or Xcode and run on a **physical** phone. ### Code {% embed url="" %} ### How to run {% stepper %} {% step %} ## Install tools Node **18+**, JDK **17**, Android Studio and/or Xcode 15+. Physical phone with USB debugging. {% endstep %} {% step %} ## Clone, install, build the plugin ```bash git clone https://github.com/Faceplugin-ltd/FaceRecognition-Ionic-Capacitor.git cd FaceRecognition-Ionic-Capacitor npm install npm run build cd example && npm install ``` {% endstep %} {% step %} ## Place native runtimes | Platform | File | Example app path | Your own app path | | -------- | ------------------------ | ----------------------------- | --------------------------------------------------------- | | Android | `facerecognitionsdk.aar` | `example/android/libfacesdk/` | `node_modules/face-recognition-capacitor/android/libs/` | | iOS | three frameworks | `ios/Frameworks/` | `node_modules/face-recognition-capacitor/ios/Frameworks/` | * Android Google Drive: [facerecognitionsdk.aar](https://drive.google.com/drive/folders/1kpzYVv9Gbm_pEpDe9-x7FGB4NWZzvez0) * iOS Google Drive: [frameworks](https://drive.google.com/drive/folders/1PKmV-o7gq7s7dDtiNgXPfCi2ZlWaRy5H) (`facerecognitionsdk`, `FaceRecognitionEngine`, `onnxruntime`) {% endstep %} {% step %} ## Sync and run ```bash cd example npm run build npx cap sync npx cap open android ``` Or `npx cap open ios`. Wait for the home status bar → **Ready**. {% endstep %} {% endstepper %} Keep demo ids so the included license works: | Platform | Id | | --------------------- | ----------------------------------- | | Android package name | `com.faceplugin.facerecognitionsdk` | | iOS bundle identifier | `com.faceplugin.facerecognitionsdk` | Demo tiles: Enroll, Identify, Capture, Attribute, Settings, About. ### License Licenses are **offline**. The sample key is only for the demo app. Request a new license key for your own app. [Request a License & Support](/help/request-a-license-and-support). Default thresholds in Settings: identify **0.67**, liveness **0.5**, pose **40°**, eye-close **0.5**. ### Integrate into your own app ```bash npm install git+https://github.com/Faceplugin-ltd/FaceRecognition-Ionic-Capacitor.git npx cap sync ``` Copy runtimes into `node_modules/face-recognition-capacitor/...` as in the table above. Set **your** `appId` in `capacitor.config.ts`. Add camera + photo-library permissions. ```ts import { getMachineCode, setActivation, init, lastLicenseError, faceDetection, templateExtraction, cropFace, SDK_SUCCESS, } from 'face-recognition-capacitor'; async function activate() { const mc = await getMachineCode(); // machine code — send when requesting a key const act = await setActivation('license key'); if (act !== SDK_SUCCESS) throw new Error(await lastLicenseError()); const initCode = await init(); if (initCode !== SDK_SUCCESS) throw new Error(`init failed: ${initCode}`); } async function enrollStill(imageUri: string) { const faces = await faceDetection(imageUri); if (faces.length !== 1) return; const template = await templateExtraction(imageUri, faces[0]); const cropB64 = await cropFace(imageUri, faces[0]); // Store template + crop in YOUR database } ``` ### APIs Call order: `getMachineCode` → `setActivation` → `init` → detect / VideoWorker → `deinit`. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. #### setActivation: This API is used to activate the SDK ```ts setActivation(license: string): Promise ``` #### init: This API is used to initialize the SDK ```ts init(): Promise ``` #### getMachineCode: This API is used to retrieve the machine code ```ts getMachineCode(): Promise ``` #### faceDetection: This API is used to detect faces ```ts faceDetection(image: ImageInput, param?: FaceDetectionParam): Promise ``` `FaceBox` includes geometry (`x1,y1,x2,y2`), pose, liveness / quality / eyes / occlusion, age / gender / emotion / mask / glasses, `landmarks`, `landmarkCount`. #### templateExtraction: This API is used to extract face template ```ts templateExtraction(image: ImageInput, faceBox: FaceBox): Promise ``` #### similarity: This API is used to calculate similarity between two templates ```ts similarity(feature1: string, feature2: string): Promise ``` Also: `getLicenseStatus`, `detect(image, crop?, flags?)`, `extractFeature`, `quality`, `cropFace`, `lastLicenseError`. #### VideoWorker: This API is used for live 1:N identify ```ts startVideoWorker(config?: VideoWorkerConfig): Promise syncVideoWorkerDatabase(featuresB64: string[], matchThreshold?: number): Promise startLivePreview() / takeLiveSnapshot() / ingestLiveCameraFrame(...) subscribeVideoWorker(listener) stopVideoWorker() ``` Optional session helpers in the example: `IdentifySession`, `CaptureSession`. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Package?** `face-recognition-capacitor`. Prefer Capacitor over Cordova for new Ionic apps. **Offline?** Yes after `setActivation` / `init` with a license key for your app id. ### Related documentation * [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Ionic Cordova](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-cordova-sdk) · [Glossary](/help/resources/glossary) * [ID Document Recognition Ionic Capacitor SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-capacitor-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Ionic Cordova Faceplugin Face Recognition Ionic Cordova SDK. On-premise face matching and liveness. Legacy Cordova plugin. Prefer Capacitor for new Ionic apps. Fully on-premise **Face Recognition SDK for Ionic Cordova**. Plugin folder: `Faceplugin/`. Plugin id: `face-recognition-cordova`. Prefer [Ionic Capacitor](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-capacitor-sdk) for new projects. Demo package name: **`com.faceplugin.facerecognitionsdk`**. ### Code {% embed url="" %} ### How to run ### ✅ Setup Environment Node **18+**, npm, Cordova CLI, JDK **17**, Android SDK. iOS: macOS + Xcode 15+, physical iPhone. Put your Apple Team ID in `build.json`. #### 1. Install Node.js and npm ```bash node -v npm -v ``` #### 2. Get the runtimes * Android AAR: [Google Drive](https://drive.google.com/drive/folders/1kpzYVv9Gbm_pEpDe9-x7FGB4NWZzvez0) → `Faceplugin/src/android/facerecognitionsdk.aar` * iOS frameworks: [Google Drive](https://drive.google.com/drive/folders/1PKmV-o7gq7s7dDtiNgXPfCi2ZlWaRy5H) → `Faceplugin/src/ios/Frameworks/` *** ### Running the sample on Android ```bash npm install ionic cordova plugin add ./Faceplugin npm run setup:android npm run android ``` Add camera permission in `platforms/android/app/src/main/AndroidManifest.xml` if it is not already present: ```xml ``` ### Running the sample on iOS ```bash npm install ionic cordova plugin add ./Faceplugin npm run setup:ios npm run ios ``` Add `NSCameraUsageDescription` in `Info.plist`. Run on a **physical** iOS device. ### APIs Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. #### setActivation: This API is used to activate the SDK ```ts setActivation(license: string): Promise ``` #### init: This API is used to initialize the SDK ```ts init(): Promise ``` #### getMachineCode: This API is used to retrieve the machine code ```ts getMachineCode(): Promise ``` #### faceDetection: This API is used to detect faces ```ts faceDetection(image: ImageInput, param?: FaceDetectionParam): Promise ``` #### templateExtraction: This API is used to extract face template ```ts templateExtraction(image: ImageInput, faceBox: FaceBox): Promise ``` #### similarity: This API is used to calculate similarity between two templates ```ts similarity(feature1: string, feature2: string): Promise ``` Also: `getLicenseStatus`, `detect`, `extractFeature`, `quality`, VideoWorker (`startVideoWorker`, `ingestLiveCameraFrame`, `exportLastLiveFrame`), `deinit`. ### Integrate into your own app Prefer [Ionic Capacitor](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-capacitor-sdk) for new projects. For this Cordova plugin: 1. Place `facerecognitionsdk.aar` in `Faceplugin/src/android/` and the three iOS frameworks in `Faceplugin/src/ios/Frameworks/`. 2. `ionic cordova plugin add ./Faceplugin` then `npm run setup:android` or `setup:ios`. 3. Keep demo id **`com.faceplugin.facerecognitionsdk`** or request a key for **your** id. 4. `ionic serve` cannot load the engine — run on a physical phone. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Legacy plugin?** Yes. Prefer [Ionic Capacitor](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-capacitor-sdk) for new apps. **Offline?** Yes after activation with a license key bound to the Cordova app id. ### Related documentation * [Faceplugin Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Ionic Capacitor](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-capacitor-sdk) · [Glossary](/help/resources/glossary) * [ID Document Recognition Ionic Cordova SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-cordova-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Server Faceplugin Face SDK — Recognition + Liveness server. Combined HTTP API on port 8083 (Linux Docker, Windows, .NET). Combined **recognition + face liveness** on the server. Port **8083**. Image: `faceplugin/face-recognition-liveness-sdk`. Same recognition routes as Recognition-only, plus `POST /api/liveness`.
Linux SDKDocker image faceplugin/face-recognition-liveness-sdk. Match + /api/liveness on 8083.linux-docker.pngLinux
Windows SDKOne Windows process with detect, match, and /api/liveness.windows.pngWindows
.NET SDK.NET MAUI and C# bindings with recognition and liveness.dotnet.png.NET
* [Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) · [Mobile](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Capabilities](/products/face-recognition-sdk/capabilities) * Prefer recognition-only server? [Recognition → Server](/products/face-recognition-sdk/recognition/server-sdk) # Linux Faceplugin Face Recognition SDK Linux Docker — recognition and face liveness in one container. faceplugin/face-recognition-liveness-sdk on port 8083. detect, match, liveness. Fully on-premise **Face Recognition + Face Liveness API for Linux / Docker** in **one** container. Image: `faceplugin/face-recognition-liveness-sdk`. Default port **8083**. Gradio **9003**. One wrapper (`libFaceRecognitionSDK.so`), one license, two model packs (`far.fpk` + `fal.fpk`). Your license can unlock Recognition only, Liveness only, or both. This is **not** the recognition-only [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) (`faceplugin/face-recognition`). It is **not** the anti-spoofing-only [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) (port **8084**). Do not copy two products’ Google Drive runtimes into one `lib/cpu/` folder. All processing stays on your server. **No** biometric data is sent to Faceplugin cloud. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Pull from Docker Hub (no Google Drive download) ``` sudo docker pull faceplugin/face-recognition-liveness-sdk:latest sudo docker run -d --name faceplugin-face-recognition-liveness-sdk \ --shm-size=2gb --privileged \ -p 8083:8083 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/face-recognition-liveness-sdk:latest ``` On Docker Desktop (macOS/Windows) omit the `/etc/machine-id` volume. Port **8083** is shared with recognition-only — run **one** Face Recognition container at a time. {% endstep %} {% step %} ## Confirm health (no license yet) ``` curl -s http://127.0.0.1:8083/api/health ``` {% endstep %} {% step %} ## Copy the machine code ``` curl -s http://127.0.0.1:8083/api/machinecode ``` Send machine code to Faceplugin. Docker and host machine codes differ. {% endstep %} {% step %} ## Activate ``` curl -s -X POST http://127.0.0.1:8083/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% endstepper %} ### Run multiple containers with one license You only need this section if you want to run multiple Face Recognition + 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: ```bash sudo docker run -d --name faceplugin-face-recognition-liveness-sdk-2 \ --shm-size=2gb --privileged \ -p 8085:8083 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/face-recognition-liveness-sdk: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 Most teams use Docker Hub (above). These options are for teams that need a local image build or a native host process. #### Option B — Docker Compose (local build) 1. Clone the repo and download the Google Drive runtime into `./lib/cpu/` (files directly in that folder, not a nested zip folder): ``` git clone https://github.com/Faceplugin-ltd/FaceRecognition-LivenessDetection-Docker.git cd FaceRecognition-LivenessDetection-Docker ``` Drive folder: [FaceRecognition-LivenessDetection-Docker runtime](https://drive.google.com/drive/folders/1Lzz3eb_JMDZ0xyGtnGzxsUmMbgaYzin6). Confirm: ``` ls lib/cpu/libFaceRecognitionSDK.so lib/cpu/libfar-eng.so lib/cpu/far.fpk lib/cpu/libfal-eng.so lib/cpu/fal.fpk ``` 2. Build and start: ``` # 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 ``` Detached Compose has no TTY, so activate with `POST /api/activate` after you receive a license key. #### Option C — Native Linux (no Docker) Requires the same `./lib/cpu/` layout as Option B. Needs glibc **2.38+** (for example Ubuntu 24.04). ``` cd FaceRecognition-LivenessDetection-Docker pip3 install -r requirements.txt ./run.sh ``` Copy the machine code from the terminal, then activate with `POST /api/activate` or paste the license key when the process prompts you. {% hint style="info" %} Control routes (`/api/health`, `/api/machinecode`, `/api/activate`, `/api/licenseStatus`) return a JSON **envelope**. Process POSTs return **engine JSON** as the HTTP body. Native `./run.sh` sets `LD_PRELOAD` for liveness VFS hooks — Docker images already do this. {% endhint %} ### APIs Same recognition routes as [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk), **plus** liveness: | Endpoint | Purpose | | ------------------------ | --------------------------------- | | `GET /api/health` | Process is listening (no license) | | `GET /api/machinecode` | Machine code | | `GET /api/licenseStatus` | License capabilities | | `GET /api/backend` | `"cpu"` | | `POST /api/activate` | Activate and init | | `POST /api/detect` | Detect faces | | `POST /api/quality` | Quality checks | | `POST /api/feature` | Extract template | | `POST /api/match` | Compare two photos | | `POST /api/similarity` | Compare two templates | | `POST /api/liveness` | Passive face anti-spoofing | Full reference: [Face Recognition HTTP API](/integration/http-api/face-recognition). Liveness: [Face Liveness HTTP API](/integration/http-api/face-liveness). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). Process POSTs return **engine JSON** as the body. There is **no** `POST /api/identify` (no server-side 1:N gallery). ### Try it ```bash curl -s http://127.0.0.1:8083/api/health IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8083/api/detect \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" curl -s -X POST http://127.0.0.1:8083/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` Score **≥ 0.5** → Real / pass (same threshold family as Face Liveness on **8084**). Local Gradio: `DEMO_PORT=9003 API_BASE=http://127.0.0.1:8083 python3 demo.py` (Detect, Quality, Match, **Liveness**). ### FAQ **Is this one container for recognition and liveness?** Yes. Image `faceplugin/face-recognition-liveness-sdk`, port **8083**, including `POST /api/liveness`. **Prefer two separate products?** Use [Face Recognition Linux](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) on **8083** and [Face Liveness Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) on **8084**. **Windows combined package?** [Face Recognition + Liveness Windows SDK](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-windows). ### Related documentation * [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) (recognition only) · [Glossary](/help/resources/glossary) * [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) * [Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Choose a product](/getting-started/choose-a-product) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) # Windows Faceplugin Face Recognition SDK Windows — recognition and face liveness in one process. HTTP API on port 8083 including POST /api/liveness. No Docker. Fully on-premise **Face Recognition + Face Liveness HTTP API for Windows** in **one** process. Default port **8083**. Gradio **9003**. No Docker on Windows. One wrapper (`FaceRecognitionSDK.dll`), one license, two model packs (`far.fpk` + `fal.fpk`). Your license can unlock Recognition only, Liveness only, or both. This is **not** the recognition-only [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk). It is **not** the anti-spoofing-only [Face Liveness Detection Windows SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) (port **8084**). Do not copy two products’ Google Drive runtimes into one `lib\cpu\` folder. For Docker combined, use [Face Recognition + Liveness Linux SDK](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) (`faceplugin/face-recognition-liveness-sdk`). All processing stays on your machine. **No** biometric data is sent to Faceplugin cloud. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Copy the runtime Copy the CPU libraries from Google Drive into `lib\cpu\` (see the repo README for the current folder link). {% endstep %} {% step %} ## Install and run ``` pip install -r requirements.txt run.bat ``` {% endstep %} {% step %} ## Copy the machine code ``` curl -s http://127.0.0.1:8083/api/machinecode ``` Send machine code to Faceplugin. Copy it from the terminal if curl is not available. {% endstep %} {% step %} ## Activate ``` curl -s -X POST http://127.0.0.1:8083/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% endstepper %} {% hint style="info" %} Some routes wrap the result in a small JSON object (an **envelope**). Process POSTs return **engine JSON** as the body. Port **8083** is shared with recognition-only — run **one** Face Recognition HTTP service at a time. {% endhint %} ### APIs Same recognition routes as [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk), **plus** liveness: | Endpoint | Purpose | | ------------------------ | --------------------------------- | | `GET /api/health` | Process is listening (no license) | | `GET /api/machinecode` | Machine code | | `GET /api/licenseStatus` | License capabilities | | `GET /api/backend` | `"cpu"` | | `POST /api/activate` | Activate and init | | `POST /api/detect` | Detect faces | | `POST /api/quality` | Quality checks | | `POST /api/feature` | Extract template | | `POST /api/match` | Compare two photos | | `POST /api/similarity` | Compare two templates | | `POST /api/liveness` | Passive face anti-spoofing | Full reference: [Face Recognition HTTP API](/integration/http-api/face-recognition). Liveness: [Face Liveness HTTP API](/integration/http-api/face-liveness). Shared control routes: [Shared endpoints](/integration/http-api/shared). There is **no** `POST /api/identify` (no server-side 1:N gallery). ### Try it ```bash curl -s http://127.0.0.1:8083/api/health IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8083/api/detect \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" curl -s -X POST http://127.0.0.1:8083/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` Local Gradio: `run_demo.bat` on **9003** (Detect, Quality, Match, **Liveness**). ### FAQ **Is this one Windows process for recognition and liveness?** Yes. Public repo [FaceRecognitionSDK-Windows](https://github.com/Faceplugin-ltd/FaceRecognitionSDK-Windows), including `POST /api/liveness`. **Prefer two separate products?** Use [Face Recognition Windows](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) on **8083** and [Face Liveness Windows](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) on **8084**. ### Related documentation * [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) (recognition only) · [Glossary](/help/resources/glossary) * [Face Recognition + Liveness Linux SDK](/products/face-recognition-sdk/recognition-and-liveness/recognition-and-liveness-server/face-recognition-sdk-linux) * [Face Liveness Detection Windows SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) * [Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Choose a product](/getting-started/choose-a-product) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) # .NET Faceplugin Face Recognition .NET SDK. Fully on-premise face matching and liveness for C# and .NET. Activate, Init, DetectFace, Compare. ### Code {% embed url="" %} ### Setup 1. Copy`FacepluginSDK.dll` to your project. 2. Include `FaceSDK.cs` to your project. ### APIs #### GetHardwareId: This API is used to get hardware id of the device on which this SDK is running on ```csharp public String GetHardwareId() ``` #### Activate: This API is used to activate the SDK ```csharp public int Activate(String license) ``` #### Init: This API is used to initialize the SDK call these functions ```csharp public int Init(string modelPath) ``` #### DetectFace: This API is used to detect faces, face liveness and get face attributes including yaw, roll, pitch, eye closedness, face occlusion, call these functions ```csharp public int DetectFace(byte[] rgbData, int width, int height, int stride, [In, Out] ResultBox[] faceBoxes, int faceBoxCount) ``` #### Compare: This API is used to get the similarity of two face images ```csharp public int Compare(byte[] rgbData1, int width1, int height1, int stride1, byte[] rgbData2, int width2, int height2, int stride2, [In, Out] float[] similarity) ``` #### {% hint style="info" %} This page follows the public [FaceRecognition-.Net](https://github.com/Faceplugin-ltd/FaceRecognition-.Net) API (`GetHardwareId`, `Activate`, `Init`, `DetectFace`, `Compare`). If your DLL exposes different method names, [contact us](/help/request-a-license-and-support) with the methods you see. {% endhint %} [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **What APIs does this page ship?** Public GitHub names: `GetHardwareId`, `Activate`, `Init`, `DetectFace`, `Compare`. **Is this the Windows HTTP API?** No. For `POST /api/detect` on port **8083**, use [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk). ### Related documentation * [Faceplugin Face Recognition Server SDK](/products/face-recognition-sdk/recognition/server-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) (HTTP API) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # ID Document SDK Faceplugin ID Document SDK: passport OCR / MRZ, authenticity-only Document Liveness, and OCR plus authenticity in one Document Reader engine. ### Overview **Faceplugin ID Document SDK** covers **document recognition** (OCR / MRZ / barcode), **authenticity-only liveness**, and **recognition + liveness** in one Document Reader engine. **Coverage:** **16,900** document templates across **255** countries and territories. Full list: [Supported documents PDF](/products/id-document-recognition-sdk/capabilities#document-type-classification--worldwide-coverage). What the product can do: [Capabilities](/products/id-document-recognition-sdk/capabilities). * [**Recognition**](/products/id-document-recognition-sdk/recognition) — OCR / MRZ overview (install via Document Reader platforms) * [**Liveness**](/products/id-document-recognition-sdk/id-document-liveness-sdk) — authenticity only, no OCR (port **8086**) * [**Recognition + Liveness**](/products/id-document-recognition-sdk/recognition-and-liveness) — Document Reader mobile + server (**recommended** for eKYC) It is **not** a face matching SDK — use the [Face SDK](/products/face-recognition-sdk) after you have a selfie. ```mermaid flowchart LR Capture --> Locate Locate --> OCR_MRZ OCR_MRZ --> Authenticity Authenticity --> JSON ``` All processing stays on the device or in your own server — **NO** data leaves your machine. ### Features * [x] ID card, passport, and driver license recognition * [x] MRZ, barcode, QR, and OCR * [x] Document detection and type classification (**16,900** templates) * [x] Live camera locate overlay on mobile * [x] Image quality analysis * [x] Face, portrait, and signature extraction * [x] Authenticity / document liveness (when licensed) * [x] On-premise document verification API (port **8082**) ### Passport OCR, ID card verification, MRZ | Capability | Where it runs | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Passport OCR / MRZ | `recognize` / `documentRecognition` / `documentProcess` on every platform | | ID card and driver license OCR | Same APIs | | Barcode / QR | Same APIs | | Document verification API (HTTP) | Linux / Windows port **8082** | | Authenticity without OCR | Dedicated [ID Document Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) on Linux **8086**, or `documentLiveness` on this engine when licensed | Every platform returns the same field set: [Document result JSON](/products/id-document-recognition-sdk/document-result-json). Authenticity names: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). Deep dive: [Capabilities](/products/id-document-recognition-sdk/capabilities). ### Supported documents The engine classifies **passports, national IDs, driver licenses, visas, residence permits**, and many specialized credentials worldwide. Download the customer catalog: {% file src="/files/Bw9iEbYJuRY2RfdjSTio" %} Faceplugin Supported Documents (PDF) {% endfile %} Coverage: **16,900** templates across **255** countries and territories — full list in the PDF. Confirm a specific series with [support](/help/request-a-license-and-support) if needed. ### Modes Pick **Capabilities**, then a mode.
CapabilitiesRecognition, authenticity-only liveness, and OCR + authenticity.Capabilities
RecognitionOCR / MRZ overview — platforms under Recognition + Liveness.Recognition
LivenessAuthenticity-only Linux API on port 8086.Liveness
Recognition + LivenessDocument Reader mobile + server — recommended for eKYC.Recognition + Liveness
### FAQ **Does Faceplugin read passports?** Yes — on-premise passport OCR, MRZ, and crops. See [Capabilities](/products/id-document-recognition-sdk/capabilities) and [Document result JSON](/products/id-document-recognition-sdk/document-result-json). **Is this an ID card verification API?** Yes — `POST /api/documentRecognition` and `POST /api/documentProcess` on port **8082**, or on-device APIs on mobile. **Does it read the MRZ?** Yes, when the document template includes an MRZ. **Is document liveness included?** Only with a Liveness-capable license on this engine, or via the dedicated Document Liveness Linux product. **How many document types?** **16,900** templates in **255** countries — [PDF catalog](/products/id-document-recognition-sdk/capabilities#document-type-classification--worldwide-coverage). ### Use cases * **Passport / ID onboarding** — classify the document, run OCR / MRZ / barcode (`recognize` / `documentRecognition`) * **Digital KYC** — extract fields and portrait crops for downstream face match * **Banking & fintech** — verify IDs on-device or via HTTP on port **8082** * **Government e-services** — read national IDs and licenses from **16,900** templates * **Fraud prevention** — optional document authenticity when your license includes it (or use [Document Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk)) ### Related documentation * [Capabilities](/products/id-document-recognition-sdk/capabilities) · [Recognition](/products/id-document-recognition-sdk/recognition) · [Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) · [Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) · [Face SDK](/products/face-recognition-sdk) * [Request a License](/help/request-a-license-and-support) · [Try it](/getting-started/try-it) · [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) * [Passport OCR & ID verification](/help/resources/passport-ocr-and-id-verification) · [Combining products (eKYC)](/getting-started/choose-a-product) * [SDK comparison](/help/comparisons) · [Status codes](/help/resources/status-codes) # Capabilities Faceplugin ID Document SDK capabilities: passport OCR / MRZ, document authenticity (Recognition + Liveness license), and authenticity-only Document Liveness on port 8086. What the Faceplugin **ID Document SDK** can do — **recognition**, **liveness** (authenticity-only), and **recognition + liveness** — before you pick a platform. | Mode | What you get | Start install | | -------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | **Recognition** | OCR, MRZ, barcode, classify, crops (port **8082** / mobile) | [Recognition](/products/id-document-recognition-sdk/recognition) | | **Liveness** | Authenticity only — no OCR (port **8086**) | [Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) | | **Recognition + Liveness** | OCR plus document authenticity in one Document Reader engine | [Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) | ```mermaid flowchart LR Capture --> Classify Classify --> OCR_MRZ OCR_MRZ --> Barcode Barcode --> Quality Quality --> Authenticity Authenticity --> JSON ``` All processing stays on the device or on **your** server. Document images are not sent to a Faceplugin cloud. ## Recognition ### Passport OCR and MRZ reading Faceplugin reads **passports** (including ePassport data pages) with visual-zone OCR and ICAO-style **MRZ** parsing (TD1 / TD2 / TD3 style zones where the template supports them). Typical outputs include document number, names, dates, nationality, and check digits — returned in the same JSON shape on every platform. See [Document result JSON](/products/id-document-recognition-sdk/document-result-json). **APIs:** mobile `recognize` / `documentProcess`; server `POST /api/documentRecognition` and `POST /api/documentProcess` on port **8082**. ### National ID and driver license verification The same engine classifies and reads **national ID cards**, **driver licenses**, and related credentials. You do not pre-select country or series for typical stills — the SDK identifies the document type, then runs OCR / MRZ / barcode as the template allows. ### Barcode and QR parsing Where the document template defines them, Faceplugin decodes **1D/2D barcodes** and **QR** codes and maps payload fields into the result JSON (for example PDF417 on many North American licenses). ### Document type classification — worldwide coverage Faceplugin classifies **16,900** document templates across **255** countries and territories: passports, IDs, licenses, visas, residence permits, and specialized cards. {% file src="/files/Bw9iEbYJuRY2RfdjSTio" %} Faceplugin Supported Documents (PDF) — full catalog {% endfile %} Confirm an uncommon series with [support](/help/request-a-license-and-support) if needed. ### Image quality, crop, and portrait extraction The engine can assess capture quality, locate the document, and return **cropped** document images plus **portrait** (and signature when present) for downstream face match or archival storage in **your** database. ### Recognition API (port 8082) | Route | Role | | ------------------------------- | ------------------- | | `GET /api/machinecode` | Machine code | | `POST /api/activate` | Activate license | | `POST /api/documentRecognition` | OCR / MRZ / barcode | | `POST /api/documentProcess` | Combined pipeline | Images: [Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) `faceplugin/document-reader`, [Windows](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-windows-sdk). ## Liveness (authenticity only) Dedicated **ID Document Liveness** checks whether the image is a **physical ID** or an attack (screen replay, printout, digital source, substituted portrait). **No OCR / MRZ / barcode.** * Public SDK today: **Linux / Docker** on port **8086** * Route: `POST /api/documentLiveness` after `POST /api/activate` * Field names: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields) See [Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) · [Linux](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk). This is **not** face anti-spoofing — use the [Face SDK](/products/face-recognition-sdk/capabilities) for selfies. ## Recognition + Liveness With a **Liveness-capable license**, the Document Reader engine runs **document authenticity** alongside OCR on the same process (port **8082** / mobile). Same security field names as Document Liveness. Prefer authenticity **without** reading fields? Use dedicated Liveness on **8086**. ## Which mode to pick | Need | Mode | | -------------------------------------------------- | -------------------------- | | Passport OCR / MRZ / barcode | **Recognition** | | Authenticity gate without reading PII | **Liveness** (**8086**) | | OCR and authenticity in one Document Reader engine | **Recognition + Liveness** | ## eKYC: document then face 1. Capture ID → Document Recognition (**8082** or mobile). 2. Optional document authenticity (same engine or Document Liveness **8086**). 3. Capture selfie → [Face SDK](/products/face-recognition-sdk/capabilities) liveness / match (**8084** / **8083** / mobile). 4. Compare portrait crop to selfie with Face Recognition. See [Combining products](/getting-started/choose-a-product#combining-products-ekyc). ## Platforms | Mode | Surfaces | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Recognition | OCR via Document Reader — install under [Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) | | Liveness | [Server](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk) (Linux **8086**, authenticity only) | | Recognition + Liveness | [Mobile](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Server](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) (Document Reader, port **8082**) | ## Use cases * **Passport OCR / MRZ** — read travel documents on-device or on port **8082** * **ID card and license verification** — classify and extract fields for KYC * **Authenticity gate** — reject screen / print attacks before or with OCR * **Split architecture** — Document Liveness **8086** + OCR in another service ## FAQ **Is this a passport OCR SDK?** Yes — on-premise passport OCR and MRZ, plus ID cards and licenses. **Does Faceplugin read the MRZ?** Yes, when the document template includes an MRZ. **How many document types are supported?** **16,900** templates in **255** countries and territories — see the PDF above. **Does Document Liveness read the MRZ?** No. Use Recognition for OCR / MRZ. ### Related documentation * [ID Document SDK](/products/id-document-recognition-sdk) · [Try it](/getting-started/try-it) · [Glossary](/help/resources/glossary) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) · [Request a License](/help/request-a-license-and-support) * [Face SDK capabilities](/products/face-recognition-sdk/capabilities) # Document result JSON ID Document Recognition result JSON. documentName, OCR, MRZ, barcode, verification, image quality, images, and security fields returned by recognize and documentProcess on every platform. `recognize` (mobile) and `POST /api/documentProcess` (Linux / Windows) return the **same idea**: one JSON object. Dedicated `documentRecognition` / `documentLiveness` (and the matching HTTP paths) use the same JSON shape with recognition-only or authenticity-only fields populated. Flutter, React Native, and Ionic **normalize Android output** so it matches this **iOS-shaped** contract. Parse this object in your app. Do not copy the demo Result screen. ### Top-level fields | Field | Meaning | | -------------- | ------------------------------------------------------------------------------------------ | | `errorCode` | Optional engine error | | `documentName` | Document type name | | `countryName` | Issuing country | | `score` | Document / locate confidence | | `msg` | Optional message | | `verification` | Field and document checks | | `imageQuality` | Capture quality checks (omitted when `response.ImageQuality` is `"none"`) | | `ocr` | Visual-zone fields | | `mrz` | Machine-readable zone | | `barcode` | Barcode / QR fields | | `images` | Crops (portrait, document, signature, …). Recognition only; omitted on `documentLiveness`. | | `security` | Authenticity / document liveness (license-gated) | ### `verification` | Key | Meaning | | ---------- | ----------------------------- | | `overall` | Whole-document verdict | | `docType` | Type check | | `expiry` | Expiry check | | `text` | OCR consistency | | `mrz` | MRZ check | | `security` | Authenticity rolled up | | `imageQA` | Image quality rolled up | | `portrait` | Portrait check | | `reasons` | Optional list of fail reasons | Values: **0** Pass, **1** Fail, **2** Not checked. ### `imageQuality.checks` Typical keys (order used in the Android demo): `focus`, `glares`, `resolution`, `colorness`, `perspective`, `bounds`, `portrait`, `handwritten`, `brightness`, `occlusion`. Each check uses `CheckResult`: **0** Fail, **1** Pass, **2** Not checked. That is **not** the same 0/1/2 mapping as `verification`. ### `images[]` Each item: `name`, `image` (often base64), optional `source`. Present on `documentRecognition` / `recognize` / `documentProcess`. **Omitted** on `documentLiveness`. ### `security` Authenticity / document liveness (license-gated). Full key list: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). | Key | Meaning | | --------- | ------------------------------------------------------------------------------------------------------------------------- | | `overall` | Rolled-up authenticity (`success` / `fail` / `notChecked`) | | `label` | Human-readable status | | `pages[]` | Per-page groups (`pageIndex`, `overall`, `label`, plus RGB check keys such as `photoOriginAnalysis`, `hologramIntegrity`) | Each group is `{ title, result, checks? }` or `{ title, score }` for pattern percent. Nested checks are omitted when they were not run. Needs authenticity `"normal"` on `recognize` / `"Authenticity": "normal"` on the server. `"none"` skips Security. ### Locate JSON (camera overlay only) `locateDocument` is **not** folded into the recognize result. Expect `score`, `position.corners`, and sometimes `_locateImageWidth` / `_locateImageHeight`. **No OCR** and **no image quality** on this path (`ImageQuality` is `"none"`). Flutter, React Native, and Ionic ship typed helpers (`recognizeResult`, `rows`, `summary`, `images`, `securityRows`) so you do not write a 600-line parser. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Same JSON on every platform?** Yes — `recognize` and `POST /api/documentProcess` share this field set. **Authenticity key names?** [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). ### Related documentation * [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields) · [Glossary](/help/resources/glossary) * [ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Document security check fields Faceplugin document security check fields for RGB captures. JSON keys and titles returned in security.pages: photoOriginAnalysis, hologramIntegrity, physicalDocument. When authenticity is **on**, `recognize` / `documentProcess` add a `security` object. Faceplugin Document Reader accepts **RGB** stills (phone camera, gallery, or a color JPEG/PNG). UV, IR, and axial-light checks are not returned. Each check object includes a `title` you can show in the UI and a `result` (`success`, `fail`, or `notChecked`). `securityPattern` uses `score` (percent) instead of `result`. Not every document produces every key. ```json { "security": { "overall": "success", "label": "Authentic", "pages": [ { "pageIndex": 0, "overall": "success", "label": "Authentic", "photoOriginAnalysis": { "title": "Photo origin analysis", "result": "success", "checks": { "photoIntegrity": { "title": "Photo authenticity", "result": "success" } } } } ] } } ``` ### Page-level keys Skip these when listing checks: `pageIndex`, `overall`, `label`. Front is `pageIndex` **0**, back **1**. | Key | Title | | --------------------- | --------------------------------------- | | `physicalDocument` | Physical document verification | | `photoOriginAnalysis` | Photo origin analysis | | `securityPattern` | Security pattern analysis | | `barcodeFormat` | Barcode format verification | | `portraitMatch` | Portrait consistency verification | | `portraitRegion` | Portrait area verification | | `opticallyVariable` | Optically variable feature verification | | `hologramIntegrity` | Hologram integrity verification | | `kineticFeature` | Kinetic optical verification | | `letterpressPattern` | Letterpress pattern verification | | `textCrosscheck` | Text consistency analysis | | `mrzCrosscheck` | MRZ consistency analysis | ### Nested `checks` keys Present only when that sub-check ran. Each value is `{ "title", "result" }`. | Key | Title | | ------------------- | --------------------------------- | | `blankArea` | Unused area | | `fillArea` | Printed background | | `photoArea` | Document photo | | `mrzArea` | Machine-readable zone | | `hologramPresent` | Hologram presence | | `hologramStill` | Still hologram | | `hologramAngles` | Multi-angle hologram | | `hologramMotion` | Moving hologram | | `patternIntact` | Unbroken pattern | | `patternAligned` | Pattern alignment | | `patternColor` | Pattern color match | | `patternWeight` | Pattern line thickness | | `photoSize` | Photo size | | `photoIntegrity` | Photo authenticity | | `photoColor` | Photo color | | `photoShape` | Photo shape | | `photoCorners` | Photo corners | | `portraitVsGhost` | Photo vs ghost image | | `portraitVsPrint` | Photo vs printed portrait | | `portraitVsLive` | Photo vs live face | | `portraitVsBarcode` | Photo vs barcode image | | `barcodeArea` | Barcode area | | `barcodeSize` | Barcode size | | `barcodePattern` | Barcode pattern verification | | `ghostImage` | Ghost portrait | | `ghostClarity` | Ghost image clarity | | `barcodeVsLive` | Barcode vs live face | | `barcodeVsGhost` | Barcode vs ghost image | | `ghostVsLive` | Ghost vs live face | | `extraVsPrint` | Extra photo vs printed portrait | | `extraVsLive` | Extra photo vs live face | | `extraVsBarcode` | Extra photo vs barcode | | `extraVsGhost` | Extra photo vs ghost | | `displayAttack` | Display attack detection | | `digitalSource` | Digital source detection | | `digitalSeal` | Digital signature | | `opticalInk` | Optical ink verification | | `laserInk` | Laser-etched ink | | `hiddenFeature` | Hidden feature verification | | `contactChip` | Contact chip | | `microprint` | Microprint | | `printedText` | Printed text | | `depthAnalysis` | 3D depth analysis | | `faceDetection` | Face verification | | `faceLandmarks` | Face landmarks | | `noFace` | Restricted area is empty | | `headPose` | Head position | | `documentGeometry` | Document geometry analysis | | `monochromeCopy` | Monochrome reproduction detection | | `variablePrint` | Variable print verification | | `ageMatch` | Age consistency | | `sexMatch` | Sex consistency | | `lowContrast` | Low-contrast element | {% hint style="info" %} A missing key means that check was not run for this image — not that it passed. {% endhint %} Top-level recognize contract: [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Related documentation * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) · [Glossary](/help/resources/glossary) * [ID Document Liveness SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk) * [ID Document Recognition Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Recognition Faceplugin ID Document SDK — Recognition. OCR / MRZ / barcode via the Document Reader product. **OCR / MRZ / barcode / classify / crops** without a dedicated authenticity-only service. There is no separate “OCR-only” public repository. Document Reader apps expose recognition APIs, and with a Liveness-capable license they also run authenticity — see [Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) for all Document Reader platforms (mobile, Linux, Windows, Node). * **Capabilities:** [ID Document SDK capabilities](/products/id-document-recognition-sdk/capabilities) (Recognition section) * **Result shape:** [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * **Install platforms:** [Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) For authenticity **without** OCR, use [Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) on port **8086**. # Liveness Faceplugin ID Document Liveness SDK. On-premise document anti-spoofing HTTP API for Linux and Docker. Screen, print, and substitution attacks. No OCR. Port 8086. ### Overview **Faceplugin ID Document Liveness SDK** checks whether the image is a **physical ID** or an attack: a screen replay, a printout, a digitally created page, or a substituted portrait. This product does **not** read fields. OCR, MRZ (machine-readable zone), and barcodes are turned off. For **passport OCR plus authenticity** in one engine, use [ID Document Recognition](/products/id-document-recognition-sdk) with a Liveness-capable license. This is **not** face anti-spoofing — use [Face Liveness Detection](/products/face-recognition-sdk/liveness-detection-sdk) for selfies. Today the public **SDK** is **Linux / Docker** (HTTP port **8086**). There is no public mobile SDK. ```mermaid flowchart LR PageImage --> Authenticity Authenticity --> SecurityJSON ``` ### Features * [x] Document authenticity and liveness checks * [x] Screen replay and digital-source detection * [x] Printed copy checks * [x] Front and back (multi-page) images * [x] On-premise (your machine only) ### Platforms
Server SDKLinux / Docker authenticity-only HTTP API on port 8086.Server
### FAQ **Does this read the MRZ?** No. Use ID Document Recognition for OCR / MRZ. **How do I call it?** `POST /api/documentLiveness` after `POST /api/activate`. See [Linux SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk). ### Use cases * **KYC authenticity gate** — reject screen replays and printouts before OCR (`POST /api/documentLiveness`, port **8086**) * **Split architecture** — run authenticity-only on Linux while OCR runs in another service * **Fraud prevention** — physical-ID checks without reading personal fields ### Related documentation * [ID Document SDK](/products/id-document-recognition-sdk) · [Face SDK](/products/face-recognition-sdk) · [Glossary](/help/resources/glossary) * [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields) * [Request a License](/help/request-a-license-and-support) · [Try it](/getting-started/try-it) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Server Faceplugin ID Document Liveness Server SDK. On-premise document anti-spoofing HTTP API for Linux Docker on port 8086. POST /api/documentLiveness. No OCR. Document authenticity only (screen replay, print, substitution). Optical character recognition (OCR), MRZ, and barcodes are **off**. Typical call order: `GET /api/machinecode` → send machine code → `POST /api/activate` → `POST /api/documentLiveness`. Default port **8086**. For **fields plus authenticity** in one engine, use [ID Document Recognition Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) with a Liveness-capable license. There is no public mobile SDK for this product.
Linux SDKDocker image faceplugin/document-liveness. HTTP API on port 8086.linux-docker.pngLinux
```mermaid flowchart LR PageImage --> Authenticity Authenticity --> SecurityJSON ``` ### FAQ **Does this read the MRZ?** No. OCR is off. Use [ID Document Recognition](/products/id-document-recognition-sdk). **API?** `POST /api/documentLiveness` on port **8086** after `POST /api/activate`. ### Related documentation * [ID Document Liveness SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk) · [Linux SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk) · [Glossary](/help/resources/glossary) * [ID Document Recognition Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # 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 {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). 1. 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. 2. Health (no license): `curl -s http://127.0.0.1:8086/api/health` 3. Get machine code: `GET /api/machinecode` 4. 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: ```bash 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](https://drive.google.com/drive/folders/1_V05Nvcdc3WfOPuyquFyGIW-4CDj8aAm) 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](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/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](/integration/http-api/document-liveness). Shared control routes: [Shared endpoints](/integration/http-api/shared). 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: ```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 ```bash 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](/products/id-document-recognition-sdk/document-security-check-fields). [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Document anti-spoofing API?** `POST /api/documentLiveness` on port **8086**. No OCR. **Need passport OCR too?** Use [ID Document Recognition Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) with a Liveness-capable license, or run both containers and call each API from your backend. ### Related documentation * [Faceplugin ID Document Liveness Server SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk) · [Glossary](/help/resources/glossary) * [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) (OCR + optional authenticity) * [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) (face anti-spoofing) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Recognition + Liveness Faceplugin ID Document SDK — Recognition + Liveness. Document Reader with OCR and optional document authenticity (same engine / license flags). **Document Reader** products: passport / ID OCR **and** document authenticity (document liveness) in one engine when the license allows. Port **8082** on server. Public READMEs list OCR, MRZ, barcode, quality, crops, and authenticity / security checks. APIs include `recognize` / `documentProcess` and `documentLiveness` (authenticity-only call on the same SDK). * **Capabilities:** [ID Document SDK capabilities](/products/id-document-recognition-sdk/capabilities) * **Security fields:** [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields) * **Mobile:** [Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) * **Server:** [Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) — Linux `faceplugin/document-reader`, Windows, Node Prefer authenticity **without** OCR? Use dedicated [Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) on port **8086**. For production eKYC, prefer Document Reader (this mode) over splitting OCR and Document Liveness unless you need an authenticity-only service — see [Deploy and host](/integration/deploy-and-host/architecture). # Mobile Faceplugin ID Document Recognition Mobile SDK. On-premise passport OCR and ID card verification for Android, iOS, Flutter, React Native, and Ionic. Capture and read identity documents on the device. Camera locate overlay (corners only — no OCR on every frame), then `recognize` / `documentProcess` for OCR, MRZ, barcode, image quality, and optional authenticity. Every platform returns the same field set: [Document result JSON](/products/id-document-recognition-sdk/document-result-json). Authenticity names: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). For HTTP APIs on Windows, Linux, and Docker, use [Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk). Prefer [Ionic Capacitor](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-capacitor-sdk) over Cordova for new Ionic apps.
Android SDKNative AAR. Camera, Gallery, and Result screens.android.pngAndroid
iOS SDKdocsdk.framework. Same Camera and Gallery flow as Android.apple-logo-3-300x300.pngiOS
Flutter SDKdocument_reader_sdk plugin plus an example app.flutter.pngFlutter
React Native SDKdocument-reader-sdk plugin. Yarn 3, not Expo Go.react.pngReact Native
Ionic Capacitor SDKdocument-reader-capacitor for new Ionic apps.ionic.pngIonic Capacitor
Ionic Cordova SDKLegacy Cordova plugin. Prefer Capacitor for new projects.cordova.pngIonic Cordova
```mermaid flowchart LR Capture --> Locate Locate --> OCR_MRZ OCR_MRZ --> Authenticity Authenticity --> JSON ``` ### FAQ **Does this do passport OCR on the phone?** Yes. `recognize` / `documentProcess` return OCR, MRZ, barcode, and crops. See [Document result JSON](/products/id-document-recognition-sdk/document-result-json). **Is authenticity included?** Only with a Liveness-capable license. Otherwise use [ID Document Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk). ### Related documentation * [Capabilities](/products/id-document-recognition-sdk/capabilities) · [Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) · [Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) · [ID Document SDK](/products/id-document-recognition-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Mobile SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Android Faceplugin ID Document Recognition Android SDK. On-premise OCR, MRZ, barcode, and authenticity. documentreadersdk.aar in libdocsdk, not libfacesdk. Fully on-premise **ID Document Recognition SDK for Android**. Reads passports, national IDs, and driver licenses. Place `documentreadersdk.aar` in **`libdocsdk/`**, not `libfacesdk/`. Public class: `com.faceplugin.documentreadersdk.DocumentReaderSDK`. Demo id: **`com.faceplugin.documentreader`**. ### Code {% embed url="" %} ### Setup 1. Copy the SDK (`libdocsdk` folder) to the `root` folder in your project. Place `documentreadersdk.aar` from [Google Drive](https://drive.google.com/drive/folders/1nDSfvj0WtC1lZgzwFd7471ECVtk-nuYH) inside `libdocsdk/`. 2. Add SDK to the project in `settings.gradle` ``` rootProject.name = "YourProjectName" include ':app' include ':libdocsdk' ``` 3. Add dependency to your `build.gradle` ``` implementation project(path: ':libdocsdk') ``` 4. minSdk **24**, JDK **17**. Call **setActivation → init** off the UI thread. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ### APIs #### setActivation: This API is used to activate the SDK ```java public static int setActivation(Context context, String license); ``` #### init: This API is used to initialize the SDK ```java public static int init(Context context) throws IOException; ``` #### getMachineCode: This API is used to retrieve the machine code ```java public static String getMachineCode(Context context); ``` #### getLicenseStatus: This API is used to read recognition and authenticity flags ```java public static String getLicenseStatus(); public static String lastLicenseError(); ``` #### locateDocument: This API is used to find document corners on a preview frame ```java public static String locateDocument(Bitmap bitmap); ``` | **Input** | Preview bitmap. | | ---------------- | ------------------------------------------------------------ | | **Return value** | JSON: corners + score. **No OCR.** Use for the overlay only. | Also: `locateVideoFrame(byte[] nv21, int width, int height, int rotation)` for camera NV21 frames. #### recognize: This API is used to run FullProcess (OCR / MRZ / barcode / authenticity) ```java public static String recognize(Bitmap bitmap); public static String recognize(Bitmap front, Bitmap back, boolean authenticity); public static String recognize(Bitmap front, Bitmap back, String authenticityMode); ``` | **Input** | One image, or front + optional back. Authenticity `"normal"` / `"none"` or boolean. | | ---------------- | -------------------------------------------------------------------------------------- | | **Return value** | JSON: OCR / MRZ / barcode, verification, image quality, crops, security (if licensed). | Verification: **0** Pass, **1** Fail, **2** Not checked. #### documentRecognition: This API is used to run OCR / MRZ / barcode / image quality only ```java public static String documentRecognition(Bitmap front); public static String documentRecognition(Bitmap front, Bitmap back); ``` Authenticity is always off. #### documentLiveness: This API is used to run authenticity / security only ```java public static String documentLiveness(Bitmap front); public static String documentLiveness(Bitmap front, Bitmap back); ``` OCR / MRZ / barcode / image quality are always off. #### startNewSession: This API is used to open a FullProcess session before recognize ```java DocumentReaderSDK.startNewSession("{\"scenario\":\"FullProcess\",\"series\":false}"); ``` #### deinit: This API is used to unload the engine ```java public static String deinit(); ``` `deinit()` returns a **String** (not `int`). ### Run the demo 1. Place `documentreadersdk.aar` in `libdocsdk/` (not `libfacesdk`). 2. Keep the demo package name **`com.faceplugin.documentreader`**. 3. Run on a **physical** phone. 4. Home: Camera, Gallery, About. Result tabs: OCR / MRZ / barcode, Liveness (security), Images, Raw JSON. ### Screenshots | Home | Camera | Gallery | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Faceplugin Document Reader Android home | Faceplugin Document Reader camera overlay | Faceplugin Document Reader gallery | | Result | Security | Images | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Faceplugin Document Reader result | Faceplugin Document Reader security | Faceplugin Document Reader crops | ### License Licenses are **offline**. Request a new license key for your own app. Parse the JSON with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Try it (after the demo compiles) ```java DocumentReaderSDK.setActivation(context, DEMO_LICENSE); DocumentReaderSDK.init(context); String json = DocumentReaderSDK.recognize(front, back, "normal"); ``` [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Passport OCR on Android?** Yes. `DocumentReaderSDK.recognize` / `documentProcess` return OCR, MRZ, barcode, and crops. See [Document result JSON](/products/id-document-recognition-sdk/document-result-json). **Offline?** Yes after `setActivation` / `init` with a license key for the demo app id (or yours). ### Related documentation * [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [iOS](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ios-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Android SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) * [Face Liveness Detection Android SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-android-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # iOS Faceplugin ID Document Recognition iOS SDK. On-premise OCR, MRZ, and authenticity. docsdk.framework, setActivation, initSDK, locateDocument, recognize. Fully on-premise **ID Document Recognition SDK for iOS**. Native class: `DocSDK`. Demo bundle: **`com.faceplugin.documentreader.app`**. ### Code {% embed url="" %} ### Setup 1. Unzip `docsdk.framework.zip` from [Google Drive](https://drive.google.com/drive/folders/1do6Ws_BlXGkR_K9jI_ULd1zHjqLGSP4q) next to `DocumentReader.xcodeproj`. Engine may nest as `Frameworks/dcrcore.framework` inside `docsdk.framework`. 2. Add `docsdk.framework` to the project in Xcode (**Embed & Sign**). Bridging: `#import `. 3. Set **your** Signing Team. Physical iPhone, iOS 13+, Xcode 15+. Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. ### APIs #### setActivation: This API is used to activate the SDK ```objectivec +(int)setActivation:(NSString*)license; ``` #### initSDK: This API is used to initialize the SDK ```objectivec +(int)initSDK; ``` #### getMachineCode: This API is used to retrieve the machine code ```objectivec +(NSString*)getMachineCode; ``` #### getLicenseStatus: This API is used to read recognition and authenticity flags ```objectivec +(NSString*)getLicenseStatus; +(NSString*)lastLicenseError; ``` #### locateDocument: This API is used to find document corners on a preview frame ```objectivec +(NSString*)locateDocument:(UIImage*)image; ``` **No OCR.** Overlay only. #### recognize: This API is used to run FullProcess ```objectivec +(NSString*)recognize:(UIImage*)image; +(NSString*)recognize:(UIImage*)image authenticity:(BOOL)authenticity; +(NSString*)recognize:(UIImage*)image authenticityMode:(NSString*)mode; +(NSString*)recognizeFront:(UIImage*)front back:(UIImage*)back authenticityMode:(NSString*)mode; ``` #### documentRecognition: This API is used to run OCR / MRZ / barcode / image quality only ```objectivec +(NSString*)documentRecognition:(UIImage*)image; +(NSString*)documentRecognitionFront:(UIImage*)front back:(UIImage*)back; ``` #### documentLiveness: This API is used to run authenticity / security only ```objectivec +(NSString*)documentLiveness:(UIImage*)image; +(NSString*)documentLivenessFront:(UIImage*)front back:(UIImage*)back; ``` #### startNewSession: This API is used to open a FullProcess session before recognize ```objectivec +(NSString*)startNewSession:(NSString*)optionsJson; ``` #### deinitSDK: This API is used to unload the engine ```objectivec +(NSString*)deinitSDK; ``` ### Run the demo 1. Unzip `docsdk.framework.zip` next to `DocumentReader.xcodeproj`. Engine may nest as `Frameworks/dcrcore.framework` inside `docsdk.framework`. 2. Keep demo bundle **`com.faceplugin.documentreader.app`**. 3. Physical iPhone, iOS 13+, Xcode 15+. 4. Home: Camera, Gallery, About. Result JSON matches [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### License Licenses are **offline**. Request a new license key for your own app. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Passport OCR on iOS?** Yes. `recognize` returns OCR, MRZ, barcode, and crops. **Offline?** Yes after `setActivation` / `initSDK` for bundle `com.faceplugin.documentreader.app` (or your own license key). ### Related documentation * [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Android](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-android-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition iOS SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ios-sdk) * [Face Liveness Detection iOS SDK](/products/face-recognition-sdk/liveness-detection-sdk/mobile-sdk/liveness-detection-ios-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Flutter Faceplugin ID Document Recognition Flutter SDK. On-premise OCR, MRZ, and authenticity. document\_reader\_sdk plugin for Android and iOS. Fully on-premise **ID Document Recognition SDK for Flutter**. Package: `document_reader_sdk`. Android output is **normalized** to the iOS-shaped JSON. Parse it with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Code {% embed url="" %} ### How to Run {% stepper %} {% step %} ## Install tools Flutter **3.44+** (see the package `pubspec.yaml`). JDK **17**. Run `flutter doctor` and fix reported issues. {% endstep %} {% step %} ## Clone and bootstrap ``` git clone https://github.com/Faceplugin-ltd/ID-Document-Recognition-Flutter.git cd ID-Document-Recognition-Flutter dart run tool/bootstrap.dart ``` {% endstep %} {% step %} ## Place native runtimes | Platform | File | Example app path | Your own app path | | -------- | ----------------------- | ---------------------------- | ------------------------ | | Android | `documentreadersdk.aar` | `example/android/libdocsdk/` | Plugin `android/libs/` | | iOS | `docsdk.framework` | `ios/Frameworks/` | Plugin `ios/Frameworks/` | * Android Google Drive: [documentreadersdk.aar](https://drive.google.com/drive/folders/1nDSfvj0WtC1lZgzwFd7471ECVtk-nuYH) * iOS Google Drive: [docsdk.framework](https://drive.google.com/drive/folders/1do6Ws_BlXGkR_K9jI_ULd1zHjqLGSP4q) {% endstep %} {% step %} ## Run the example ``` cd example flutter pub get flutter run ``` Physical phone. Keep Android `com.faceplugin.documentreader`, iOS `com.faceplugin.documentreader.app`. {% endstep %} {% endstepper %} ### License Licenses are **offline**. Request a new license key for your own app. ### Integrate into your own app ```yaml dependencies: document_reader_sdk: git: url: https://github.com/Faceplugin-ltd/ID-Document-Recognition-Flutter.git ``` Then `flutter pub get`, copy runtimes, `cd ios && pod install`, and **rebuild** the native app. ```dart import 'package:document_reader_sdk/document_reader_sdk.dart'; Future boot() async { final machine = await getMachineCode(); // machine code final act = await setActivation('license key'); if (act != sdkSuccess) { print(await lastLicenseError()); return; } final code = await init(); if (code != sdkSuccess) return; final locateJson = await locateDocument(imagePath); final resultJson = await recognize(frontPath, backPath, true); } ``` Authenticity accepts `true` / `false` or `'normal'` / `'none'`. Image input: file path, `file://` URI, content URI, or base64 / `data:` URL. ### APIs Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. #### setActivation: This API is used to activate the SDK ```dart Future setActivation(String license) ``` #### init: This API is used to initialize the SDK ```dart Future init() ``` #### getMachineCode: This API is used to retrieve the machine code ```dart Future getMachineCode() ``` #### locateDocument: This API is used to find document corners on a preview frame ```dart Future locateDocument(ImageInput image) ``` #### recognize: This API is used to run FullProcess ```dart Future recognize(ImageInput front, [ImageInput? back, Object authenticity = true]) ``` #### documentRecognition: This API is used to run OCR / MRZ / barcode / image quality only ```dart Future documentRecognition(ImageInput front, [ImageInput? back]) ``` #### documentLiveness: This API is used to run authenticity / security only ```dart Future documentLiveness(ImageInput front, [ImageInput? back]) ``` Also: `getLicenseStatus`, `startNewSession`, `recognizeResult` (typed `DocResult`), `deinit`. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Package?** `document_reader_sdk`. **Passport OCR?** Yes. `recognize` / `documentProcess`. Typed helper: `recognizeResult`. ### Related documentation * [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [React Native](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-react-native-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Flutter SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-flutter-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # React Native Faceplugin ID Document Recognition React Native SDK. On-premise OCR, MRZ, and authenticity. document-reader-sdk plugin, not Expo Go. Fully on-premise **ID Document Recognition SDK for React Native**. Package: `document-reader-sdk`. **Not Expo Go.** Physical arm64 device. Android output is **normalized** to the iOS-shaped JSON. Parse it with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Code {% embed url="" %} ### How to Run {% stepper %} {% step %} ## Install tools Node **18+**, Yarn, React Native environment. Use Yarn as in the repo. **Not Expo Go.** {% endstep %} {% step %} ## Clone and install ```bash git clone https://github.com/Faceplugin-ltd/ID-Document-Recognition-React-Native.git cd ID-Document-Recognition-React-Native yarn cd example && yarn ``` {% endstep %} {% step %} ## Place native runtimes | Platform | File | Example app path | Your own app path | | -------- | ----------------------- | ---------------------------- | -------------------------------------------------- | | Android | `documentreadersdk.aar` | `example/android/libdocsdk/` | `node_modules/document-reader-sdk/android/libs/` | | iOS | `docsdk.framework` | `ios/Frameworks/` | `node_modules/document-reader-sdk/ios/Frameworks/` | * Android Google Drive: [documentreadersdk.aar](https://drive.google.com/drive/folders/1nDSfvj0WtC1lZgzwFd7471ECVtk-nuYH) * iOS Google Drive: [docsdk.framework](https://drive.google.com/drive/folders/1do6Ws_BlXGkR_K9jI_ULd1zHjqLGSP4q) {% endstep %} {% step %} ## Run on a phone ``` yarn cd example yarn android ``` iOS: `cd example/ios && pod install`, then open the workspace. Wait until Home shows Ready. {% endstep %} {% endstepper %} Keep demo ids: Android `com.faceplugin.documentreader`, iOS `com.faceplugin.documentreader.app`. Android: `minSdkVersion 24` and `abiFilters 'arm64-v8a'`. ### License Licenses are **offline**. Install from GitHub, not npm: ```bash yarn add document-reader-sdk@git+https://github.com/Faceplugin-ltd/ID-Document-Recognition-React-Native.git ``` Rebuild the **native** app after install — a JS reload is not enough. ### Integrate into your own app ```ts import { getMachineCode, setActivation, init, recognize, locateDocument, SDK_SUCCESS, } from 'document-reader-sdk'; const act = await setActivation('license key'); if (act === SDK_SUCCESS) await init(); const locateJson = await locateDocument(imageUri); const resultJson = await recognize(frontUri, backUri, 'normal'); ``` Permissions: CAMERA + photo library (`READ_MEDIA_IMAGES` / `READ_EXTERNAL_STORAGE` maxSdk 32; `NSCameraUsageDescription` / `NSPhotoLibraryUsageDescription`). ### APIs Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. #### setActivation: This API is used to activate the SDK ```ts setActivation(license: string): Promise ``` #### init: This API is used to initialize the SDK ```ts init(): Promise ``` #### getMachineCode: This API is used to retrieve the machine code ```ts getMachineCode(): Promise ``` #### locateDocument: This API is used to find document corners on a preview frame ```ts locateDocument(image: ImageInput): Promise ``` **No OCR.** Overlay only. #### recognize: This API is used to run FullProcess ```ts recognize(front, back?, authenticity?): Promise ``` Authenticity: `true` / `false` or `'normal'` / `'none'`. #### documentRecognition: This API is used to run OCR / MRZ / barcode / image quality only ```ts documentRecognition(front, back?): Promise ``` #### documentLiveness: This API is used to run authenticity / security only ```ts documentLiveness(front, back?): Promise ``` Also: `getLicenseStatus`, `startNewSession`, `deinit`. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Package?** `document-reader-sdk`. Yarn 3; not Expo Go. **Same JSON as iOS?** Yes — the plugin normalizes Android output. See [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Related documentation * [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Flutter](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-flutter-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition React Native SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-react-native-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Ionic Capacitor Faceplugin ID Document Recognition Ionic Capacitor SDK. On-premise OCR, MRZ, and authenticity. document-reader-capacitor plugin for new Ionic apps. Fully on-premise **ID Document Recognition SDK for Ionic Capacitor**. Package: `document-reader-capacitor`. Prefer this for **new** Ionic apps. Cordova is a [different repo](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-cordova-sdk). `ionic serve` / the browser **cannot** load the engine. Open Android Studio or Xcode and run on a **physical** phone. Parse results with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Code {% embed url="" %} ### How to run {% stepper %} {% step %} ## Install and build the plugin ```bash git clone https://github.com/Faceplugin-ltd/ID-Document-Recognition-Ionic-Capacitor.git cd ID-Document-Recognition-Ionic-Capacitor npm install && npm run build cd example && npm install ``` {% endstep %} {% step %} ## Place native runtimes | Platform | File | Example / plugin path | | -------- | ----------------------- | ----------------------------------------------------------------------------------------------- | | Android | `documentreadersdk.aar` | `example/android/libdocsdk/` (your app: `node_modules/document-reader-capacitor/android/libs/`) | | iOS | `docsdk.framework` | `ios/Frameworks/` | * Android Google Drive: [documentreadersdk.aar](https://drive.google.com/drive/folders/1nDSfvj0WtC1lZgzwFd7471ECVtk-nuYH) * iOS Google Drive: [docsdk.framework](https://drive.google.com/drive/folders/1do6Ws_BlXGkR_K9jI_ULd1zHjqLGSP4q) {% endstep %} {% step %} ## Sync and run ```bash cd example npx cap sync npx cap open android ``` Or `npx cap open ios`. Add camera + photo-library permissions. {% endstep %} {% endstepper %} ### APIs Status codes: **0** Success, **1** Invalid license, **2** Expired, **3** Not activated, **4** Init failed. Call order: `getMachineCode` → `setActivation` → `init` → `locateDocument` / `recognize` → `deinit`. #### setActivation: This API is used to activate the SDK ```ts setActivation(license: string): Promise ``` #### init: This API is used to initialize the SDK ```ts init(): Promise ``` #### getMachineCode: This API is used to retrieve the machine code ```ts getMachineCode(): Promise ``` #### locateDocument: This API is used to find document corners on a preview frame ```ts locateDocument(image: ImageInput): Promise ``` #### recognize: This API is used to run FullProcess ```ts recognize(front, back?, authenticity?): Promise ``` #### documentRecognition: This API is used to run OCR / MRZ / barcode / image quality only ```ts documentRecognition(front, back?): Promise ``` #### documentLiveness: This API is used to run authenticity / security only ```ts documentLiveness(front, back?): Promise ``` Also: `getLicenseStatus`, `startNewSession`, `startLivePreview` / `takeLiveSnapshot`, `deinit`. [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Package?** `document-reader-capacitor`. Prefer Capacitor over Cordova. **JSON contract?** [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Related documentation * [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Ionic Cordova](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-cordova-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Ionic Capacitor SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-capacitor-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Ionic Cordova Faceplugin ID Document Recognition Ionic Cordova SDK. Legacy DocumentReaderPlugin layout. Prefer Capacitor for new ID scanning apps. Use this guide only if you already have a **Cordova** Ionic app. The native engine matches Capacitor. New projects should use [Ionic Capacitor](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-capacitor-sdk). ### Code {% embed url="" %} ### How to run ### ✅ Setup Environment Install Node.js, Ionic CLI, and Cordova. Physical device recommended (`ionic serve` cannot load the engine). 1. Place `documentreadersdk.aar` at `DocumentReaderPlugin/src/android/documentreadersdk.aar`. 2. Place `docsdk.framework` at `DocumentReaderPlugin/src/ios/Frameworks/docsdk.framework`. 3. Run: ```bash npm install npm run setup:android npm run android ``` Gradle is bootstrapped via `scripts/with-gradle.js`. iOS: put your Apple Team ID in root `build.json`. Physical iPhone; `docsdk` is device arm64. You can also add the plugin from a local path: ```bash ionic cordova plugin add ./DocumentReaderPlugin ionic cordova build android ionic cordova run android ``` Drive: [Android](https://drive.google.com/drive/folders/1nDSfvj0WtC1lZgzwFd7471ECVtk-nuYH) · [iOS](https://drive.google.com/drive/folders/1do6Ws_BlXGkR_K9jI_ULd1zHjqLGSP4q). The Android demo license key string in this repo can differ from Capacitor / React Native / Flutter; it is still bound to `com.faceplugin.documentreader`. ### APIs Same activate → init → locate / recognize / documentRecognition / documentLiveness sequence as the other mobile Document Reader Apps. Status codes **0**–**4**. Native camera helpers: `startLivePreview` / `takeLiveSnapshot` / `stopLivePreview`. Plugin folder: `DocumentReaderPlugin/`. #### setActivation: This API is used to activate the SDK ```ts setActivation(license: string): Promise ``` #### init: This API is used to initialize the SDK ```ts init(): Promise ``` #### recognize: This API is used to run FullProcess ```ts recognize(front, back?, authenticity?): Promise ``` Also: `getMachineCode`, `locateDocument`, `documentRecognition`, `documentLiveness`, `getLicenseStatus`, `deinit`. Parse JSON with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Legacy plugin?** Yes. Prefer [Ionic Capacitor](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-capacitor-sdk) for new apps. ### Related documentation * [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Ionic Capacitor](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk/id-document-recognition-ionic-capacitor-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Ionic Cordova SDK](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-ionic-cordova-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Server Faceplugin document verification API for Windows and Linux Docker. On-premise passport OCR, MRZ, and authenticity HTTP on port 8082. documentRecognition and documentProcess. ID Document Recognition as an HTTP API on **your** machine. Send page images; receive OCR, MRZ, barcode, image quality, and optional authenticity JSON. Typical call order: `GET /api/machinecode` → send machine code → `POST /api/activate` → `POST /api/documentRecognition` / `documentLiveness` / `documentProcess`. Default port **8082**. Parse results with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). Authenticity field names: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). Authenticity **without** OCR is a separate product: [ID Document Liveness SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk). For on-device capture, use [Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk).
Linux SDKDocker image faceplugin/document-reader. Same HTTP API as Windows.linux-docker.pngLinux
Windows SDKHTTP API on port 8082. No Docker on Windows.windows.pngWindows
Node SDKHTTP API on port 8082. Optional native libDocSDK.javascript.pngNode.js
```mermaid flowchart LR PageImage --> documentProcess documentProcess --> OCR_MRZ OCR_MRZ --> Authenticity Authenticity --> JSON ``` ### FAQ **Is this a document verification API?** Yes. Port **8082**: `POST /api/documentRecognition`, `/api/documentLiveness`, `/api/documentProcess`. **Passport OCR without authenticity?** Use `documentRecognition`. Authenticity-only is [ID Document Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) on port **8086**. ### Related documentation * [Capabilities](/products/id-document-recognition-sdk/capabilities) · [Faceplugin ID Document Recognition Mobile SDK](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [ID Document Recognition SDK](/products/id-document-recognition-sdk) · [Glossary](/help/resources/glossary) * [ID Document Liveness Server SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Linux Faceplugin document verification API for Linux Docker. On-premise passport OCR, MRZ, and authenticity. POST /api/documentProcess on port 8082. Fully on-premise **ID Document Recognition HTTP API for Linux / Docker**. Image: `faceplugin/document-reader`. Default port **8082**. Gradio **9002**. Reads ID cards, passports, and driver licenses. OCR, MRZ, barcode / QR, image quality, crops, and optional authenticity (document liveness). All processing stays on your server. **No** biometric data is sent to Faceplugin cloud. {% hint style="warning" %} `--shm-size=2gb` is required. A smaller shm size can crash the engine. {% endhint %} ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Pull from Docker Hub (no Google Drive download) ``` sudo docker pull faceplugin/document-reader:latest sudo docker run -d --name faceplugin-document-reader \ --shm-size=2gb --privileged \ -p 8082:8082 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/document-reader:latest ``` On Docker Desktop omit the `/etc/machine-id` volume. {% endstep %} {% step %} ## Confirm health (no license yet) ``` curl -s http://127.0.0.1:8082/api/health ``` {% endstep %} {% step %} ## Activate ``` curl -s http://127.0.0.1:8082/api/machinecode curl -s -X POST http://127.0.0.1:8082/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% endstepper %} ### Run multiple containers with one license You only need this section if you want to run multiple Document Reader 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: ```bash sudo docker run -d --name faceplugin-document-reader-2 \ --shm-size=2gb --privileged \ -p 8083:8082 \ -v /etc/machine-id:/etc/machine-id:ro \ faceplugin/document-reader: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-Recognition-Docker.git cd ID-Document-Recognition-Docker ``` Put the [Google Drive runtime](https://drive.google.com/drive/folders/16DFGKtyGbyL-0gfVOmNVaQ9vgXCYDr2M) 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 ``` **Try online:** [Hugging Face Space](https://huggingface.co/spaces/Faceplugin-Ltd/ID-Document-Recognition-SDK) (Gradio UI → your Linux API). ### License [Request a License & Support](/help/request-a-license-and-support). ### Try it ```bash curl -s http://127.0.0.1:8082/api/health IMG=$(base64 -w0 id-front.jpg) curl -s -X POST http://127.0.0.1:8082/api/documentProcess \ -H 'Content-Type: application/json' \ -d "{\"images\":[{\"image\":\"$IMG\",\"page_idx\":0}],\"response\":{\"OCR\":\"normal\",\"Authenticity\":\"normal\"}}" ``` **Postman:** import `postman/DocumentReader-API.postman_collection.json` from the repo. Base URL `http://127.0.0.1:8082`. **Gradio (host only):** ``` pip3 install -r requirements-demo.txt DEMO_PORT=9002 API_BASE=http://127.0.0.1:8082 python3 demo.py ``` Open . Tabs: Result, Liveness, Images, Raw JSON. Parse the engine JSON with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Integrate into your own app | Path | When to use | | ------------ | ----------------------------------------------------------- | | **HTTP** | Any language. Keep this API running and `POST` page images. | | **`sdk.py`** | Python on the same Linux host as `lib/cpu/`. | You do **not** need Gradio in production. ### 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/documentRecognition` | OCR / MRZ / barcode / image quality only | | `POST /api/documentLiveness` | Authenticity only | | `POST /api/documentProcess` | Combined OCR + optional authenticity | | `POST /api/generalProcess` | Single-image general process | Full reference: [Document Reader HTTP API](/integration/http-api/document-reader). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). Process POSTs return **engine JSON** as the body. Authenticity-only without OCR: [ID Document Liveness Linux SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk). Python: ```python import sdk sdk.activate("license.txt") sdk.init_sdk() print(sdk.document_recognition([{"image": base64_front}])) print(sdk.document_process(images, options={"response": {"OCR": "normal", "Authenticity": "normal"}})) ``` [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **Document verification API?** `POST /api/documentRecognition` / `documentProcess` on port **8082**. **Passport OCR?** Yes — OCR, MRZ, barcode, crops in the same JSON. ### Related documentation * [Faceplugin ID Document Recognition Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) · [Windows](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-windows-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) * [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) * [ID Document Liveness Linux SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Windows Faceplugin ID Document Recognition Windows SDK. Fully on-premise OCR and authenticity HTTP API on port 8082. documentRecognition, documentProcess. Fully on-premise **ID Document Recognition HTTP API for Windows**. Default port **8082**. Gradio **9002**. No Docker on Windows — use [Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) for Docker. Reads ID cards, passports, and driver licenses. Same routes as [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk). Parse results with [Document result JSON](/products/id-document-recognition-sdk/document-result-json). ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). {% stepper %} {% step %} ## Copy the runtime Copy the CPU libraries from [Google Drive](https://drive.google.com/drive/folders/1YfHUwnXO0E2NSvS_81nTNO2z3mKVO85g) into `lib\cpu\`. {% endstep %} {% step %} ## Install and run ``` pip install -r requirements.txt run.bat ``` Demo UI: `run_demo.bat` after the API is up. {% endstep %} {% step %} ## Copy the machine code and activate ``` curl -s http://127.0.0.1:8082/api/machinecode curl -s -X POST http://127.0.0.1:8082/api/activate \ -H 'Content-Type: text/plain' \ --data-binary @license.txt ``` {% endstep %} {% endstepper %} ### APIs Same as [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk): | 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/documentRecognition` | OCR / MRZ / barcode / image quality only | | `POST /api/documentLiveness` | Authenticity only | | `POST /api/documentProcess` | Combined OCR + optional authenticity | | `POST /api/generalProcess` | Single-image general process | Full reference: [Document Reader HTTP API](/integration/http-api/document-reader). Shared control routes: [Shared endpoints](/integration/http-api/shared). Some routes wrap the result in a small JSON object (an **envelope**). Process POSTs return **engine JSON** as the body. ### Try it ```bash curl -s http://127.0.0.1:8082/api/health IMG=$(base64 -w0 id-front.jpg) curl -s -X POST http://127.0.0.1:8082/api/documentProcess \ -H 'Content-Type: application/json' \ -d "{\"images\":[{\"image\":\"$IMG\",\"page_idx\":0}],\"response\":{\"OCR\":\"normal\",\"Authenticity\":\"normal\"}}" ``` **Postman:** import `postman/DocumentReader-API.postman_collection.json` from the repo. Base URL `http://127.0.0.1:8082`. Gradio **9002**. Authenticity names: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). [Request a License & Support](/help/request-a-license-and-support) · [Contact us](/help/contact-us) ### FAQ **API?** Same routes as Linux on port **8082**. No Docker on Windows. **Authenticity?** `documentLiveness` / `documentProcess` when the license includes it. ### Related documentation * [Faceplugin ID Document Recognition Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) · [Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk) * [Face Liveness Detection Windows SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) * [Request a License](/help/request-a-license-and-support) · [Status codes](/help/resources/status-codes) * [Combining products (eKYC)](/getting-started/choose-a-product) · [SDK comparison](/help/comparisons) # Node.js Faceplugin ID Document Recognition Node.js HTTP API. Same documentProcess routes as Python on port 8082. Optional native libDocSDK; stub without it. Node.js **HTTP API** with the same routes as the Python Document Reader server (`POST /api/documentProcess`, license routes, …). Default port **8082**. No Docker. Native `libDocSDK` is optional. Without it the server can run a demo stub (`DOCSDK_STUB=1`) that mimics the Gradio UI shape. For production OCR, use the Python Linux/Windows HTTP SDK or provide the native library. ### Code {% embed url="" %} ### Setup Sizing: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). ```bash npm start ``` Web demos (React / Vue / Angular / JavaScript) can point at this process on **8082**. Also public: [Go](https://github.com/Faceplugin-ltd/ID-Document-Recognition-Go) and [C/C++](https://github.com/Faceplugin-ltd/ID-Document-Recognition-CPP) HTTP APIs with the same route family. ### APIs | Endpoint | Purpose | | ------------------------------- | ---------------------------------------- | | `GET /api/health` | Process is listening (no license) | | `GET /api/machinecode` | Machine code | | `GET /api/licenseStatus` | License status | | `POST /api/activate` | Activate | | `POST /api/documentRecognition` | OCR / MRZ / barcode / image quality only | | `POST /api/documentLiveness` | Authenticity only | | `POST /api/documentProcess` | Combined OCR + optional authenticity | | `POST /api/generalProcess` | Single-image general process | Full reference: [Document Reader HTTP API](/integration/http-api/document-reader). Shared control routes: [Shared endpoints](/integration/http-api/shared). Same route family as the Python Document Reader server. Without native `libDocSDK`, use `DOCSDK_STUB=1` for a demo stub only. ### Related documentation * [Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) · [Server SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) · [Glossary](/help/resources/glossary) * [Document result JSON](/products/id-document-recognition-sdk/document-result-json) · [Choose a product](/getting-started/choose-a-product) # Palm Recognition SDK Faceplugin open-source Palm Recognition SDK. On-premise RGB-camera palm matching with Python Anaconda. ROI extraction and compare\_two\_images. Not a Faceplugin commercial face SDK. ### Overview **Faceplugin Palm Recognition SDK** is a **free, on-premise** Python sample for palm matching from a standard **RGB camera**. It is **not** the commercial [Face Recognition SDK](/products/face-recognition-sdk) and it is **not** a document or liveness product. All processing stays on your machine. ### Features * [x] Palm Detection * [x] ROI (region of interest) extraction * [x] Template Extraction * [x] Template Matching * [x] On-premise (your machine only) ### Platforms The public sample is the [open-source Palm Recognition repository](/products/palm-recognition-sdk/open-source-palm-recognition-sdk) (Anaconda / Python on Windows in the README). ### FAQ **Does this replace Face Recognition?** No. Use [Face Recognition](/products/face-recognition-sdk) for faces. **Is there a Docker HTTP API?** Not in this sample. Commercial face/document server SDKs are Docker Hub images under each product’s Server SDK. ### Use cases * **Access control demo** — extract palm ROI and match templates in Python on your machine * **Attendance prototype** — compare two palm images with `compare_two_images` * **R\&D** — evaluate palm matching before choosing a commercial face product ### Related documentation * [Open-source Palm Recognition setup](/products/palm-recognition-sdk/open-source-palm-recognition-sdk) · [Glossary](/help/resources/glossary) * [Face Recognition SDK](/products/face-recognition-sdk) · [Request a License](/help/request-a-license-and-support) # Open Source Faceplugin open-source Palm Recognition SDK. On-premise Python Anaconda sample for RGB-camera palm matching. extract\_roi, extract\_features, compare\_two\_images. Not a commercial face SDK. ### Code {% embed url="" %} ### Overview This page is the **open-source Palm Recognition** Python sample. It matches palms from a standard **RGB camera** on **your** machine. It is **not** the commercial [Face Recognition SDK](/products/face-recognition-sdk), **not** Face Liveness, and **not** document OCR. Unlike cloud palm APIs, processing stays local. No biometric data is sent to Faceplugin. ### Setup Please download anaconda on your computer and install it. We used Windows machine without GPU for testing 1. Create anaconda environment ``` conda create -n palm python=3.9 ``` 2. Activate the environment ``` conda activate palm ``` 3. Install dependencies ``` pip install torch torchvision torchaudio pip install opencv-python pip install tqdm pip install scikit-image pip install mediapipe ``` 4. Compare two palm images in the `test_images` directory ``` python main.py ``` ### APIs and Parameters * **classify\_hand(mp\_hands, hand\_landmarks, image\_width):** determine if the hand is left hand or right hand * **extract\_roi(hands, mp\_hands, img\_path):** extract region of interest from the palm image for template matching * **extract\_features(mp\_hands, hands, path: str):** extract template from the plam image specified by the path parameter * **compare\_two\_images(mp\_hands, hands, image\_path1, image\_path2, similarity\_threshold=0.8):** compare two hand images to determine if they are the same hand or not. ### FAQ **Is this a Faceplugin commercial SDK?** No. It is a public GitHub sample. There is no license key / Docker HTTP API on this page. **Can I use it for face matching?** No. Use [Face Recognition](/products/face-recognition-sdk). ### Related documentation * [Palm Recognition SDK](/products/palm-recognition-sdk) · [Face Recognition SDK](/products/face-recognition-sdk) · [Glossary](/help/resources/glossary) * [Request a License](/help/request-a-license-and-support) · [Choose a product](/getting-started/choose-a-product) # HTTP API Faceplugin HTTP API for Linux, Docker, and Windows. Ports, response shapes, and links to per-product endpoint pages. Use this section when you run Faceplugin on **Linux, Docker, or Windows**. Those apps expose an HTTP API. Mobile SDKs use the same ideas (activate, process, JSON results). They do **not** use these URLs. Call the native or plugin methods on each mobile platform page instead. ## Base URL ``` http://{host}:{port} ``` Paths do **not** include `/v1`. | Product | Default port | What it does | | ----------------------- | -----------: | ---------------------------------------- | | ID Document Recognition | 8082 | OCR, MRZ, barcode, optional authenticity | | Face Recognition | 8083 | Detect, quality, template, 1:1 match | | Face Liveness | 8084 | Score one face image for spoofing | | ID Document Liveness | 8086 | Document authenticity only | **MRZ** means the machine-readable zone on a passport. **OCR** means reading printed text from the image. These Flask apps allow CORS from any origin (`*`). Do not treat CORS as access control. See [Production deployment](/integration/deploy-and-host/production-deployment). ## Two response shapes This is the most common integration mistake. The apps use **two** shapes. ### Envelope (shared routes) Some routes wrap the result in a small JSON object. We call that an **envelope**. These routes use an envelope: `GET /api/health`, `/api/machinecode`, `/api/backend`, `/api/licenseStatus`, and `POST /api/activate`. ```json { "success": true, "code": 0, "message": "OK", "request_id": null, "data": {} } ``` ### Engine JSON (process routes) Process routes do **not** use an envelope. They return the engine JSON as the HTTP body. Examples: `POST /api/detect`, `/api/liveness`, `/api/documentProcess`, `/api/documentRecognition`, `/api/documentLiveness`. Parse that JSON directly. Do not look for a `success` or `data` wrapper. {% hint style="info" %} `POST /api/activate` accepts raw `FP1.…` text, JSON `{"license":"FP1.…"}`, or a license file body. An empty body returns envelope `code: -1`. {% endhint %} ## Images Send a **base64** image (usually a JPEG) in JSON. Or upload the same field names as **files** with `multipart/form-data`. The path stays the same. The response JSON is the same. For template compare (`/api/similarity`), send templates as **text** fields (`feature1` / `feature2`). Do not send them as files. A **template** is a face feature vector you can store and compare later. ## What is not in these apps | Name you might expect | Shipping apps | | ------------------------------- | --------------------------------------------------------- | | `POST /api/identify` | **Not** in Face Recognition Linux / Windows | | `POST /api/documentDetect` | **Not** in Document Reader Linux / Windows | | `POST /api/documentRecognize` | **Not** — use `documentRecognition` or `documentProcess` | | `POST /api/verify` / `/api/idv` | **No** all-in-one Face Verification or IDV HTTP app | | GPU tags / `lib/gpu/` | **Not** in current Face Recognition or Face Liveness apps | ## Postman Import `postman/-API.postman_collection.json` from the repository you cloned. ## Per-product pages * [Shared endpoints](/integration/http-api/shared) — health, machine code, activate * [Face Recognition HTTP API](/integration/http-api/face-recognition) * [Face Liveness HTTP API](/integration/http-api/face-liveness) * [ID Document Recognition HTTP API](/integration/http-api/document-reader) * [ID Document Liveness HTTP API](/integration/http-api/document-liveness) ### Related documentation * [Try it](/getting-started/try-it) · [Deploy and host](/integration/deploy-and-host) · [Status codes](/help/resources/status-codes) # Shared endpoints Shared Faceplugin HTTP endpoints. GET /api/health, /api/machinecode, /api/backend, /api/licenseStatus, and POST /api/activate. These routes use a JSON envelope. Every shipping Linux and Windows Faceplugin app implements the same **shared** routes. Call these first. Confirm the process is up. Copy the machine code. Then activate. A **machine code** is a string that identifies the server or container for licensing. Process routes (`/api/detect`, `/api/liveness`, `/api/documentProcess`, and so on) are on the product API pages. Those POSTs return **raw engine JSON**. They do not use the envelope below. ## `GET /api/health` Check that the container or `run.bat` process is listening. **No license is required.** ```bash curl -s http://127.0.0.1:8083/api/health ``` | | | | ---------------- | ---------------------------------- | | **Input** | None | | **Return value** | Envelope. `data.status` is `"ok"`. | ## `GET /api/machinecode` Get the machine code for a server license. Send the returned `FPMC1.…` string to Faceplugin. | | | | ---------------- | ------------------------------------------ | | **Input** | None | | **Return value** | Envelope. `data.machinecode` is `FPMC1.…`. | {% hint style="warning" %} A Docker container and the Linux host have **different** machine codes. If you run in Docker, send the code from the **container**. {% endhint %} ## `GET /api/backend` Reports which compute backend the app uses. | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Input** | None | | **Return value** | Envelope. Face Recognition and Face Liveness return `"backend": "cpu"`. Document products may read `FACEPLUGIN_BACKEND`. | Example Document Reader `data`: ```json { "product": "DocumentReader", "sdk_version": "1.0.0", "backend": "cpu" } ``` ## `POST /api/activate` Unlocks product endpoints. On success the app also calls `init_sdk()`. {% tabs %} {% tab title="JSON / text" %} Plain `FP1.…` text, or JSON `{"license":"FP1.…"}`. {% endtab %} {% tab title="form-data" %} Field `license` as text, or a license file part named `license`. {% endtab %} {% endtabs %} | | | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | **Input** | License key or file | | **Return value** | Envelope. Success: `code` 0, `"Successfully activated"`, `data.activated` true. Failure: `code` -1, `"Invalid license"` or `"Empty license"`. | ## `GET /api/licenseStatus` Every Face and Document Linux/Windows app implements this route. **No license is required** to call it. | | | | ---------------- | --------------------------------------------- | | **Input** | None | | **Return value** | Envelope. `data` is the license object below. | **Face products** (`recognition` / `liveness`): ```json { "licensed": true, "level": 2, "levelName": "Developer", "recognition": true, "liveness": true, "label": "Recognition + Liveness" } ``` * Face Recognition only: `liveness` is always `false`. * Face Liveness only: `recognition` is always `false`. * Face Recognition + Liveness packages: both flags come from the license level (`0` recognition, `1` liveness, `2+` both). **Document products** (`recognition` / `authenticity`): ```json { "licensed": true, "level": 2, "levelName": "Developer", "recognition": true, "authenticity": true, "label": "Recognition + Liveness" } ``` ## `OPTIONS /api/` Returns HTTP 204 for CORS preflight. ## Errors Unhandled exceptions return envelope `code` **-19** and HTTP 500. Unknown paths return `code` **-10** and HTTP 404. See [Status codes](/help/resources/status-codes). ### Related documentation * [HTTP API overview](/integration/http-api) · [Request a License](/help/request-a-license-and-support) # Face Recognition Faceplugin Face Recognition HTTP API. POST /api/detect, /api/quality, /api/feature, /api/match, and /api/similarity on port 8083. JSON or form-data. CPU only. This is the **still-image** Face Recognition API. It runs on Linux Docker image `faceplugin/face-recognition` and on the Windows app. Default port **8083**. The engine is **CPU only**. Shared routes (health, machine code, activate, license status): [Shared endpoints](/integration/http-api/shared). Process POSTs return **engine JSON**. There is **no** `POST /api/identify` on the server. There is no server-side 1:N gallery. Store templates in **your** database. Compare them with `/api/similarity`. A call without a recognition license returns `code` 8 with `licenseError`. **Face Recognition + Liveness** packages expose the same Face Recognition routes **plus** [`POST /api/liveness`](/integration/http-api/face-liveness) on port **8083**. Install and run: [Face Recognition Linux SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-linux-sdk) · [Face Recognition Windows SDK](/products/face-recognition-sdk/recognition/server-sdk/face-recognition-windows-sdk). ### Try it ```bash curl -s http://127.0.0.1:8083/api/health IMG=$(base64 -w0 face.jpg) curl -s -X POST http://127.0.0.1:8083/api/detect \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$IMG\"}" ``` More one-liners: [Try it](/getting-started/try-it). ## `POST /api/detect` Detect faces in one image. {% tabs %} {% tab title="JSON" %} ```json { "image": "", "cropImage": false } ``` `crop_image` is accepted as an alias. {% endtab %} {% tab title="form-data" %} File field `image` (alias `file`). Text field `cropImage` (`true` / `false`). Same URL. {% endtab %} {% endtabs %} Python: `sdk.detect(image, crop_image=False)`. | | | | ---------------- | -------------------------------- | | **Input** | One image. Optional `cropImage`. | | **Return value** | Engine JSON (not the envelope). | ## `POST /api/quality` Run ICAO-style quality checks on a face image. Same request body as detect. Python: `sdk.quality`. | | | | ---------------- | ------------------------------ | | **Input** | One image. Optional crop flag. | | **Return value** | Engine JSON. | ## `POST /api/feature` Extract a face **template** (feature vector). Store it. Compare it later with `/api/similarity`. {% tabs %} {% tab title="JSON" %} ```json { "image": "" } ``` {% endtab %} {% tab title="form-data" %} File field `image` (alias `file`). {% endtab %} {% endtabs %} Python: `sdk.feature`. | | | | ---------------- | ------------------------------ | | **Input** | One image. | | **Return value** | Engine JSON with the template. | ## `POST /api/match` Compare **two photos** (1:1). The server detects and extracts internally. {% tabs %} {% tab title="JSON" %} ```json { "image1": "", "image2": "", "cropImage": false } ``` {% endtab %} {% tab title="form-data" %} File fields `image1` and `image2`. Text field `cropImage`. {% endtab %} {% endtabs %} Python: `sdk.match`. | | | | ---------------- | ------------------------------------ | | **Input** | Two images. Optional crop flag. | | **Return value** | Engine JSON with a similarity score. | ## `POST /api/similarity` Compare **two templates** you already extracted. ```json { "feature1": "", "feature2": "" } ``` Aliases: `template1` / `template2`. Missing features return envelope `code: -1`. Both features must decode to the **same length**. Form-data uses **text** fields (not files). ### Related documentation * [HTTP API overview](/integration/http-api) · [Face Liveness HTTP API](/integration/http-api/face-liveness) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements) # Face Liveness Faceplugin Face Liveness HTTP API. POST /api/liveness (alias /api/check\_liveness) with a JPEG on port 8084. Score 0.5 or higher is Real. CPU only. This API scores **one RGB JPEG** for presentation attacks. Examples include a printed photo, a screen replay, a mask, or a deepfake-style spoof. **PAD** means presentation attack detection (anti-spoofing). It runs on Docker image `faceplugin/face-liveness` and on the Windows app. Default port **8084**. The engine is **CPU only**. Shared routes: [Shared endpoints](/integration/http-api/shared). A call without a liveness license returns `code` 8 with `licenseError`. The combined Face Recognition + Liveness packages also expose `/api/liveness` on port **8083**. See [Face Recognition HTTP API](/integration/http-api/face-recognition). Install and run: [Face Liveness Detection Linux SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Face Liveness Detection Windows SDK](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-windows-sdk). ### Try it ```bash curl -s -X POST http://127.0.0.1:8084/api/liveness \ -H 'Content-Type: application/json' \ -d "{\"image\":\"$(base64 -w0 face.jpg)\"}" ``` ## `POST /api/liveness` Alias: `POST /api/check_liveness`. {% tabs %} {% tab title="JSON" %} ```json { "image": "", "algorithm": "all" } ``` {% endtab %} {% tab title="form-data" %} File field `image` (alias `file`). Optional text field `algorithm`. {% endtab %} {% endtabs %} | | | | ---------------- | --------------------------------------------------------------------------------------- | | **Input** | JPEG image. A missing `image` field returns envelope `code: -1` and `"image required"`. | | **Return value** | Engine JSON. Score **≥ 0.5** means Real / `pass` true. | Example shape: ```json { "score": 0.72, "result": "Real", "pass": true } ``` Python: ```python import sdk sdk.activate("license.txt") sdk.init_sdk() print(sdk.liveness(base64_jpeg)) ``` ### Related documentation * [HTTP API overview](/integration/http-api) · [Face Recognition HTTP API](/integration/http-api/face-recognition) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements) # ID Document Recognition Faceplugin ID Document Recognition HTTP API. POST /api/documentRecognition, /api/documentLiveness, /api/documentProcess, and /api/generalProcess on port 8082. This is the HTTP API for **ID Document Recognition**. It runs on Linux Docker image `faceplugin/document-reader` and on the Windows app. Default port **8082**. | Route | Use it for | | --------------------- | ----------------------------------------------------- | | `documentRecognition` | OCR, MRZ, barcode, image quality only | | `documentLiveness` | Authenticity only | | `documentProcess` | Combined pipeline (fields plus optional authenticity) | **MRZ** is the machine-readable zone on a passport. **OCR** means reading printed text from the image. Shared routes (including `GET /api/licenseStatus`): [Shared endpoints](/integration/http-api/shared). Install and run: [ID Document Recognition Linux SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) · [ID Document Recognition Windows SDK](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-windows-sdk). Result fields: [Document result JSON](/products/id-document-recognition-sdk/document-result-json). Security keys: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). ### Try it ```bash curl -s -X POST http://127.0.0.1:8082/api/documentRecognition \ -H 'Content-Type: application/json' \ -d "{\"images\":[{\"image\":\"$(base64 -w0 id.jpg)\"}]}" ``` ## `POST /api/documentRecognition` OCR / MRZ / barcode / image quality only. Authenticity is **always off**. Caller `response` flags are ignored. {% tabs %} {% tab title="JSON" %} ```json { "images": [ { "image": "", "page_idx": 0 }, { "image": "", "page_idx": 1 } ] } ``` {% endtab %} {% tab title="form-data" %} Repeated file field `images` (or a single `image` / `file`). Optional file `rfid`. Text `isCropped`. {% endtab %} {% endtabs %} | | | | ---------------- | ---------------------------------------------------------------------------------------- | | **Input** | One or more page images (base64). Same `images` shape as `documentProcess`. | | **Return value** | Engine JSON with OCR / MRZ / barcode / `imageQuality`. No `security` authenticity block. | Python: ```python import sdk sdk.activate("license.txt") sdk.init_sdk() result = sdk.document_recognition( [{"image": base64_front}, {"image": base64_back, "page_idx": 1}], ) ``` ## `POST /api/documentLiveness` Authenticity / security only. OCR / MRZ / barcode / image quality are **always off**. Caller `response` flags are ignored. Use the same image body as `documentRecognition`. The dedicated Document Liveness product on port **8086** uses this same path. On Document Reader (**8082**) it is authenticity-only against the recognition engine. | | | | ---------------- | ----------------------------------------------------------------------------------------- | | **Input** | One or more page images (base64). | | **Return value** | Engine JSON with `security` checks when the license includes Liveness. No `images` crops. | Python: `sdk.document_liveness(images)`. Also see [ID Document Liveness HTTP API](/integration/http-api/document-liveness). ## `POST /api/documentProcess` Run a full document process (fields plus optional security). {% tabs %} {% tab title="JSON" %} ```json { "images": [ { "image": "", "page_idx": 0 }, { "image": "", "page_idx": 1 } ], "rfid": "", "response": { "OCR": "normal", "MRZ": "normal", "Barcode": "normal", "ImageQuality": "normal", "Authenticity": "normal" } } ``` {% endtab %} {% tab title="form-data" %} Repeated file field `images` (or a single `image` / `file`). Optional file `rfid`. Text `options` or `response` as a JSON string. Text `isCropped`. {% endtab %} {% endtabs %} * `images` may also be a list of raw base64 strings. A single `"image"` field becomes a one-page list. * You may nest flags as `"options": { "response": {...}, "isCropped": ... }`. If you omit `options`, top-level `response` / `isCropped` are used. * `"Authenticity": "none"` skips liveness checks. `"normal"` runs them when the license includes Liveness. Windows also documents `"strict"`. * `"ImageQuality": "none"` skips capture-quality checks and omits `imageQuality` from the result. `"normal"` (default) runs them. * Optional `rfid` is a string passed through to the engine. The Gradio demo does not walk through NFC/RFID capture. | | | | ---------------- | ---------------------------------------------------- | | **Input** | One or more page images (base64) and response flags. | | **Return value** | Engine JSON (not the envelope). | Python: ```python import sdk sdk.activate("license.txt") sdk.init_sdk() result = sdk.document_process( [{"image": base64_front}, {"image": base64_back, "page_idx": 1}], rfid="", options={"response": {"OCR": "normal", "MRZ": "normal", "Barcode": "normal", "ImageQuality": "normal", "Authenticity": "normal"}}, ) ``` Session helpers on `sdk.py` (`start_new_session()`, `start_new_page()`, `unload()`, `get_license_status()`) are **not** separate HTTP routes. ## `POST /api/generalProcess` Single-image general process. ```json { "image": "", "options": {} } ``` | | | | ---------------- | --------------------------------------- | | **Input** | One base64 image. | | **Return value** | Engine JSON from `sdk.general_process`. | ### Related documentation * [HTTP API overview](/integration/http-api) · [Document result JSON](/products/id-document-recognition-sdk/document-result-json) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements) # ID Document Liveness Faceplugin ID Document Liveness HTTP API. POST /api/documentLiveness on port 8086. Authenticity only — OCR, MRZ, and barcode are off. This API runs **document authenticity** (anti-spoofing) only. It does not return OCR fields, MRZ lines, or barcodes. It runs on Docker image `faceplugin/document-liveness` on port **8086**. Shared routes (including `GET /api/licenseStatus`): [Shared endpoints](/integration/http-api/shared). If you need **fields and** authenticity together, call [ID Document Recognition HTTP API](/integration/http-api/document-reader) `documentProcess` with a Liveness-capable license. Document Reader on port **8082** also exposes `POST /api/documentLiveness` as authenticity-only. Install and run: [ID Document Liveness Linux SDK](/products/id-document-recognition-sdk/id-document-liveness-sdk/server-sdk/id-document-liveness-linux-sdk). ### Try it ```bash curl -s -X POST http://127.0.0.1:8086/api/documentLiveness \ -H 'Content-Type: application/json' \ -d "{\"images\":[{\"image\":\"$(base64 -w0 id.jpg)\"}]}" ``` ## `POST /api/documentLiveness` {% tabs %} {% tab title="JSON" %} ```json { "images": [ { "image": "", "page_idx": 0 }, { "image": "", "page_idx": 1 } ] } ``` {% endtab %} {% tab title="form-data" %} Repeated file field `images` (or a single `image` / `file`). Same URL. {% endtab %} {% endtabs %} A lone `"image"` field becomes a one-page list. Optional `options` or top-level `response` are forwarded. The product always requests authenticity. OCR / MRZ / barcode stay off. | | | | ---------------- | --------------------------------------------------------------- | | **Input** | One or more page images (base64). Front and back are supported. | | **Return value** | Engine JSON from `sdk.document_liveness`. | ```python import sdk sdk.activate("license.txt") sdk.init_sdk() print(sdk.document_liveness([{"image": base64_front}])) ``` Security field names: [Document security check fields](/products/id-document-recognition-sdk/document-security-check-fields). ### Related documentation * [HTTP API overview](/integration/http-api) · [ID Document Recognition HTTP API](/integration/http-api/document-reader) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements) # Deploy and host Deploy and host Faceplugin server SDKs. Architecture, hosting requirements, and production checklist for Linux, Docker, and Windows. Use this section when you put Faceplugin on **your** servers. Faceplugin does not host inference for you after you activate a license. | Page | Read it when you need to | | --------------------------------------------------------------------------- | ------------------------------------------------------------ | | [Architecture](/integration/deploy-and-host/architecture) | Combine products, choose HTTP vs `sdk.py`, know what you own | | [Hosting requirements](/integration/deploy-and-host/hosting-requirements) | Size CPU, RAM, disk, ports, and Docker flags | | [Production deployment](/integration/deploy-and-host/production-deployment) | Harden a first-run install for production | For eKYC servers, prefer [Face Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) and [Document Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) instead of separate recognition-only and liveness-only containers. Start with a platform page for install steps, then use this section for topology and ops. ### Related documentation * [HTTP API](/integration/http-api) · [Choose a product](/getting-started/choose-a-product) · [Request a License](/help/request-a-license-and-support) # Architecture Faceplugin server architecture. Prefer Recognition + Liveness combined packages for eKYC, HTTP vs sdk.py, and what you store in your own systems. Faceplugin ships product SDKs you combine in **your** mobile app or backend. Faceplugin does **not** ship one all-in-one identity-verification app. ## Recommended: combined Recognition + Liveness For production eKYC, prefer **combined** packages instead of running recognition and liveness as two separate Face (or Document) services: | Need | Prefer | Avoid (unless you must split) | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | Face match + face PAD | [Face Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) on **8083** (`faceplugin/face-recognition-liveness-sdk`) | Face Recognition **8083** + Face Liveness **8084** as two containers | | Document OCR + document authenticity | [Document Reader](/products/id-document-recognition-sdk/recognition-and-liveness) on **8082** with a Liveness-capable license | Document Reader **8082** + Document Liveness **8086** when you already need OCR | Use standalone [Face Liveness](/products/face-recognition-sdk/liveness-detection-sdk) (**8084**) or [ID Document Liveness](/products/id-document-recognition-sdk/id-document-liveness-sdk) (**8086**) only when you want **anti-spoofing without** matching or OCR. ## Typical eKYC flow **eKYC** means electronic know-your-customer / digital identity onboarding. ```mermaid flowchart LR ID[ID capture] --> OCR[OCR and MRZ] OCR --> DocAuth[Document authenticity] DocAuth --> Selfie[Selfie] Selfie --> FaceCombined[Face match + liveness] ``` | Step | Recommended product | | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | Read the ID + check it is real | [ID Document Recognition + Liveness](/products/id-document-recognition-sdk/recognition-and-liveness) (port **8082**) | | Check the selfie is live and match to ID photo | [Face Recognition + Liveness](/products/face-recognition-sdk/recognition-and-liveness) (port **8083**) | You own the final pass / fail decision. The SDKs return scores and fields. They do not decide your business outcome. ## Recommended topology Run **one process or container per product**. For face and documents, that product should usually be the **combined** package. ```mermaid flowchart TB subgraph customers [Your systems] MobileApp[Mobile or web app] Backend[Your backend] end subgraph faceplugin [Faceplugin on your infra] Doc8082[Document Reader :8082] Face8083[Face Recognition + Liveness :8083] end MobileApp --> Doc8082 MobileApp --> Face8083 Backend --> Doc8082 Backend --> Face8083 ``` Optional authenticity-only Document Liveness (**8086**) or Face Liveness (**8084**) only if you intentionally split services. ## One runtime per server Each product is its **own** process or container. Each has its own `lib/cpu/` (or Hub image that already includes the runtime). You do **not** install Document and Face into one App tree. To use both, run **two servers** (for example Document on **8082** and Face Recognition + Liveness on **8083**) and call both from your backend. ``` document-reader/ face-recognition-liveness/ lib/cpu/ ← Document lib/cpu/ ← Face only app.py app.py ``` {% hint style="danger" %} Do **not** dump a second product’s Google Drive folder into another product’s `lib/cpu/`. OpenCV, OpenSSL, and ONNX builds differ; files overwrite each other and the process can crash or return wrong scores. Keep one Drive runtime per App / container. {% endhint %} The Face **Recognition + Liveness** package is already one product (one Drive / one image) with recognition and face PAD together. That is not the same as merging Document + Face into one folder. ## Who owns what | You own | Faceplugin SDK owns | | ------------------------------------ | -------------------------------------------------- | | Template / person gallery database | Face detect, quality, template extract, 1:1 match | | Document JSON storage and PII policy | OCR, MRZ, barcode, document authenticity scores | | Orchestration and business decisions | Face liveness / PAD score | | TLS, reverse proxy, network access | Engine processing inside your process or container | | License request and key storage | Offline activate after you install the key | A **template** is a face feature vector. Store it in **your** database. The server Face Recognition API has **no** `POST /api/identify` gallery. ## Two ways to integrate on a server ### Option A — HTTP sidecar Run `app.py` or the Docker image. Call it from any language. ``` Your backend → HTTP API → sdk.py → lib/cpu ``` Use this when several services need the engine, or when your backend is not Python. ### Option B — In-process Python Import `sdk.py` on the **same** host as `lib/cpu/` (or inside the container). ``` Your Python process → sdk.py → lib/cpu ``` Use this when you want fewer network hops and you already run Python next to the runtime. **Gradio** (`demo` / `demo.py`) is a local UI for testing. Do not ship it in production. See [Production deployment](/integration/deploy-and-host/production-deployment). ## Mobile multi-SDK note On mobile, keep each product’s AAR or frameworks separate. Request one license **per** application id **per** product. Call one engine at a time. Face Liveness has no public Flutter or React Native SDK. Prefer Face Recognition + Liveness mobile apps (Identify includes 2D liveness), and/or a native Face Liveness module when you need PAD without matching. ### Related documentation * [Hosting requirements](/integration/deploy-and-host/hosting-requirements) · [Production deployment](/integration/deploy-and-host/production-deployment) · [HTTP API](/integration/http-api) · [Choose a product](/getting-started/choose-a-product) # Hosting requirements Faceplugin hosting requirements. CPU, RAM, disk, ports, Docker shm-size, and OS notes for Face Recognition, Face Liveness, and ID Document server SDKs. Use this page to size a host for Faceplugin **server** SDKs. Numbers match the public App README system requirement tables. Do not invent higher figures than those tables. All shipping server products are **CPU only**. There is no `lib/gpu/` package in these apps. **shm** means Docker shared memory (`--shm-size`). Document products need enough shm to unpack model packs such as `dcr.fpk`. ## Ports | Product | API port | Gradio (host only) | Docker image | Role | | ---------------------------------- | -------: | -----------------: | ------------------------------------------ | ------------------------------------------------ | | ID Document Recognition + Liveness | 8082 | 9002 | `faceplugin/document-reader` | **Recommended** for OCR + authenticity | | Face Recognition + Liveness | 8083 | 9003 | `faceplugin/face-recognition-liveness-sdk` | **Recommended** for match + face PAD | | Face Recognition (only) | 8083 | 9003 | `faceplugin/face-recognition` | Match only — no `/api/liveness` | | Face Liveness (only) | 8084 | 9004 | `faceplugin/face-liveness` | PAD only — use when you do not need match | | ID Document Liveness (only) | 8086 | 9006 | `faceplugin/document-liveness` | Authenticity only — use when you do not need OCR | Gradio is for local demos. Do not expose it in production. See [Production deployment](/integration/deploy-and-host/production-deployment). Prefer the **combined** Face and Document images for eKYC so you do not run separate recognition and liveness containers. Details: [Architecture](/integration/deploy-and-host/architecture). ## Per-product sizing | Product | Min CPU | Min RAM | Min disk | Recommended | OS notes | Docker extras | | ---------------------------------- | ------------------------------------------ | ------- | -------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | Face Recognition + Liveness | 2 cores | 4 GB | 4 GB | 4 cores / 8 GB RAM / 8 GB disk | Docker: Ubuntu 22.04 / 24.04. Native Linux needs glibc **2.38+** (for example Ubuntu 24.04). Windows 10/11 x64 | `--shm-size=2gb --privileged`. On Linux mount `/etc/machine-id:ro` | | Face Recognition (only) | 2 cores | 4 GB | 4 GB | 4 cores / 8 GB RAM / 8 GB disk | Same as combined | `--shm-size=2gb --privileged`. On Linux mount `/etc/machine-id:ro` | | Face Liveness (only) | 2 cores (Linux) / 4 cores (Windows README) | 4 GB | 4 GB | 4 cores / 8 GB RAM / 8 GB disk | Same Docker OS guidance as Face Recognition. Windows 10/11 x64 | `--shm-size=1gb --privileged`. On Linux mount `/etc/machine-id:ro` | | ID Document Recognition + Liveness | 2 cores | 4 GB | 4 GB | 4 cores / 8 GB RAM / 8 GB disk | Ubuntu 20.04+ x86\_64; recommend 22.04 / 24.04. Windows 10/11 x64. CPU only | `--shm-size=2gb` is **required**. `--privileged`. On Linux mount `/etc/machine-id:ro` | | ID Document Liveness (only) | 2 cores | 4 GB | 4 GB | 4 cores / 8 GB RAM / 8 GB disk | Align with Document Reader Linux | `--shm-size=2gb` is **required**. `--privileged`. On Linux mount `/etc/machine-id:ro` | For a typical eKYC box, plan **two** containers: Document Reader (**8082**) + Face Recognition + Liveness (**8083**). Add RAM/CPU for each. Each container keeps its own `lib/cpu/` — do not mix product Drive folders. See [Architecture](/integration/deploy-and-host/architecture). ## Docker rules * On **Docker Desktop** (macOS / Windows), omit the `/etc/machine-id` volume. * On Linux Engine, mounting `/etc/machine-id` lets several containers on the same host share one machine code for licensing. * A smaller `--shm-size` than required can crash Document Reader when `dcr.fpk` unpacks. * Docker Hub images already include the runtime. You do not need Google Drive for Option A Hub pulls. ## Mobile devices Mobile SDKs run on the phone. Prefer a **physical device** for camera work. Emulator cameras often stay black. See [Troubleshooting](/help/resources/troubleshooting). This page does not invent phone RAM minimums beyond each platform README. ### Related documentation * [Architecture](/integration/deploy-and-host/architecture) · [Production deployment](/integration/deploy-and-host/production-deployment) # Production deployment Production checklist for Faceplugin server SDKs. TLS, health checks, activate, no Gradio, networking, scale, and upgrades. Use this checklist after a first-run install works. These are **how you run** the product. They are not new product features. ## Before you go live 1. Use a Docker Hub image, or a **fixed image tag** you control. Avoid surprise `latest` changes in production if you need a locked build. 2. Do **not** run Gradio (`demo` / `demo.py`) in production. Gradio is a local test UI only. 3. Activate with `POST /api/activate`. Do not depend on an interactive terminal. Detached Compose has no TTY. 4. Point your load balancer or orchestrator at `GET /api/health`. No license is required for health. 5. Put the APIs behind **your** reverse proxy. End TLS at nginx, Caddy, or your cloud load balancer. Open only the ports you need. 6. Keep the APIs on your private network when you can. The Flask apps allow CORS from any origin (`*`). Do not treat CORS as security. 7. Run **one container or process per product**. Prefer **combined** Face Recognition + Liveness (**8083**) and Document Reader with authenticity (**8082**) instead of separate liveness-only services. To scale, add more containers. Follow the license and machine-code rules on each platform page. 8. Read logs from `docker logs` or process stdout. Faceplugin does not collect cloud telemetry from these apps. ## License and machine code A **machine code** identifies the server or container for licensing. {% hint style="warning" %} A Docker container and the Linux host have **different** machine codes. If you run in Docker, request the license with the code from the **container**. {% endhint %} On Linux, mounting `/etc/machine-id` into each container can let several containers share one machine code. On Docker Desktop, omit that volume. Each container may need its own license. Details: [Request a License & Support](/help/request-a-license-and-support). ## Upgrade path 1. Pull the new image, or replace files in `lib/cpu/`. 2. Restart the container or process. 3. Activate again if the machine code changed. 4. Smoke-test `GET /api/health` and one process endpoint (for example `/api/detect` or `/api/documentRecognition`). ## What production is not These surfaces are for evaluation only: * [Playground](https://playground.faceplugin.com/) * [Hugging Face Spaces](https://huggingface.co/Faceplugin-Ltd) * Gradio demos on ports 9002–9006 Do not point production traffic at them. ## Quick links | Topic | Page | | ------------------------- | ------------------------------------------------------------------------- | | Topology and what you own | [Architecture](/integration/deploy-and-host/architecture) | | CPU, RAM, shm, ports | [Hosting requirements](/integration/deploy-and-host/hosting-requirements) | | Endpoint contracts | [HTTP API](/integration/http-api) | | First-run curls | [Try it](/getting-started/try-it) | ### Related documentation * [Deploy and host](/integration/deploy-and-host) · [Troubleshooting](/help/resources/troubleshooting) · [Status codes](/help/resources/status-codes) # Resources Faceplugin docs resources. Glossary, FAQ, troubleshooting, status codes, SDK comparison, and changelog for on-premise Face Recognition, Face Liveness, and ID Document SDKs. Shared reference pages that apply across products. For **what each product can do**, open **Capabilities** under the product hub. For setup, open **Mobile SDK** or **Server SDK**. For server endpoints, open [HTTP API](/integration/http-api). For topology and sizing, open [Deploy and host](/integration/deploy-and-host). New here? Start with [Choose a product](/getting-started/choose-a-product) and [Try it](/getting-started/try-it) (also linked from the top of the sidebar). * [Passport OCR and ID verification](/help/resources/passport-ocr-and-id-verification) — short guide into Document capabilities * [Glossary](/help/resources/glossary) — MRZ, OCR, eKYC, 1:N, PAD, license key, machine code, ports * [FAQ](/help/resources/faq) — passport OCR, Face Recognition API, liveness, offline, Flutter, Docker vs host machine code, thresholds * [Troubleshooting](/help/resources/troubleshooting) * [Status codes](/help/resources/status-codes) * [SDK comparison](/help/comparisons) * [Changelog](/help/resources/changelog) Capability pages: [ID Document SDK](/products/id-document-recognition-sdk/capabilities) · [Face SDK](/products/face-recognition-sdk/capabilities) ### Related documentation * [Welcome](/) · [Request a License](/help/request-a-license-and-support) · [Contact us](/help/contact-us) # Passport OCR and ID verification On-premise passport OCR SDK and ID card verification API from Faceplugin. Read MRZ (machine-readable zone), barcodes, and 16,900 document templates on mobile or port 8082. Looking for an on-premise **passport OCR SDK**, **MRZ reader** (machine-readable zone), or **ID card verification API**? Faceplugin **ID Document Recognition** (Document Reader) classifies the document, runs OCR / MRZ / barcode, and optionally document authenticity — on the phone or on your server (port **8082**). Terms: [Glossary](/help/resources/glossary). * **What it can do:** [ID Document Recognition capabilities](/products/id-document-recognition-sdk/capabilities) * **Supported documents (PDF):** [catalog](/products/id-document-recognition-sdk/capabilities#document-type-classification--worldwide-coverage) — **16,900** templates, **255** countries * **Try HTTP:** [Try it](/getting-started/try-it) * **Install:** [Mobile](/products/id-document-recognition-sdk/recognition-and-liveness/mobile-sdk) · [Server](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk) For face match after the ID scan, see [Face SDK capabilities](/products/face-recognition-sdk/capabilities). ### Related documentation * [Choose a product](/getting-started/choose-a-product) · [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) · [Request a License](/help/request-a-license-and-support) # Glossary Faceplugin SDK glossary. Plain-language definitions for MRZ, OCR, eKYC, 1:1, 1:N, PAD, FRVT, license key, machine code, template, and HTTP ports used in these docs. Short definitions for terms used across Faceplugin docs. For product choice, see [Choose a product](/getting-started/choose-a-product). For common questions, see [FAQ](/help/resources/faq). ## Products and flows | Term | Meaning | | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Face Recognition** | Detect faces, extract a face **template**, and compare faces (1:1 or mobile 1:N). | | **Face Liveness** | Face **anti-spoofing** — is the camera seeing a live person, or a photo/screen/mask? | | **ID Document Recognition** (Document Reader) | Classify and read ID documents (passport OCR, MRZ, barcode, optional authenticity). | | **ID Document Liveness** | Document **authenticity only** (no OCR) — is the ID image a real card or a spoof? | | **eKYC** | Electronic know-your-customer / digital identity onboarding. Usually: scan ID → check authenticity → selfie liveness → face match. | | **On-premise / offline** | After license activation, inference runs on **your** device or server — not a Faceplugin cloud API. | ## Matching and anti-spoofing | Term | Meaning | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **1:1** | Compare two faces (or two templates) — “is this the same person?” | | **1:N Identify** | Compare one face against **many** enrolled templates. On mobile, Face Recognition demos do this with VideoWorker. The server HTTP API has **no** built-in gallery — you store templates and call `/api/similarity`. | | **Template / embedding** | Numeric face feature vector from `templateExtraction` / `POST /api/feature`. You store it in **your** database. | | **Similarity / match score** | How alike two templates (or images) are. Mobile Identify default match threshold **0.67**. | | **Passive liveness** | Anti-spoofing **without** a smile / turn-head challenge. Score a frame or JPEG. | | **Active liveness** | User must follow a challenge (smile, turn head). Faceplugin’s Face Liveness product is **passive**. Separate active demos exist on GitHub but are not the Face Liveness SDK. | | **PAD** | Presentation-attack detection — another name for face (or document) anti-spoofing. | | **Liveness score** | Face Liveness: score **≥ 0.5** → Real / pass (default in these docs). | ## Documents | Term | Meaning | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **OCR** | Optical character recognition — reading printed text from the ID image. | | **MRZ** | Machine-readable zone — the two or three lines of characters at the bottom of many passports and some IDs. | | **Document template** | A known ID layout the engine can classify (Faceplugin catalogs **16,900** templates / **255** countries). | | **Document authenticity** | Checks that the ID image is a physical document (not a screen reprint, etc.). Needs a Liveness-capable license on Document Recognition, or the Document Liveness product. | ## Licensing and servers | Term | Meaning | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **License key** | The activation string Faceplugin issues for your app id (mobile) or machine code (server). Paste it into `license.txt` or send it to `POST /api/activate`. | | **Machine code** | Server fingerprint from `GET /api/machinecode` (or the API log). Send it when you request a server license. Docker and a native host on the same PC produce **different** codes. | | **Google Drive runtime** | Large native binaries (AAR, frameworks, `.so` / `.dll`, `.fpk`) linked from each platform page — not stored on GitHub. | | **Port 8082** | ID Document Recognition HTTP API | | **Port 8083** | Face Recognition HTTP API (combined Recognition + Liveness also uses 8083 and adds `/api/liveness`) | | **Port 8084** | Face Liveness HTTP API | | **Port 8086** | ID Document Liveness HTTP API | ## Standards (as used in these docs) | Term | Meaning | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **NIST FRVT** | Face Recognition Vendor Test — Faceplugin Face Recognition is described as **evaluated** on FRVT. | | **iBeta** | Independent biometric testing lab often cited for liveness. These docs **do not** claim iBeta certification; ask Faceplugin for a certification statement if you need one. | ### Related documentation * [FAQ](/help/resources/faq) · [Choose a product](/getting-started/choose-a-product) · [Try it](/getting-started/try-it) * [Status codes](/help/resources/status-codes) · [Troubleshooting](/help/resources/troubleshooting) # FAQ Faceplugin SDK FAQ. Passport OCR, ID verification, Face Recognition API, passive vs active liveness, offline licensing, Flutter, Docker machine codes, and thresholds. ## What can Faceplugin ID Document Recognition (Document Reader) do? On-premise **passport OCR**, **MRZ reading**, ID card and driver license verification, barcode/QR, document type classification (**16,900** templates / **255** countries), and optional document authenticity. See [Document capabilities](/products/id-document-recognition-sdk/capabilities) and [Passport OCR & ID verification](/help/resources/passport-ocr-and-id-verification). ## Is Faceplugin a passport OCR SDK / MRZ reader? Yes. The ID Document Recognition SDK reads passports and MRZ (when the template includes one), plus national IDs and licenses. HTTP API on port **8082**. ## What is a face recognition SDK? A library that detects faces, extracts a template (embedding), and compares templates. Faceplugin’s commercial SDK runs **on-premise**. You store templates in **your** database. See [Face SDK capabilities](/products/face-recognition-sdk/capabilities). ## Is there a Face Recognition API? Yes. Linux Docker and Windows expose an HTTP API on port **8083** (`/api/detect`, `/api/match`, `/api/similarity`). The combined Recognition + Liveness packages also expose `/api/liveness` on the same port. Full reference: [Face Recognition HTTP API](/integration/http-api/face-recognition). Overview: [HTTP API](/integration/http-api). ## What is passive liveness detection? The engine scores a camera frame or JPEG **without** a smile / turn-head challenge. Faceplugin Face SDK **Liveness** is **passive** anti-spoofing. These docs do **not** claim iBeta certification. Contact Faceplugin if you need a certification statement. See [Face SDK capabilities](/products/face-recognition-sdk/capabilities). ## What is the difference between active and passive liveness? **Passive:** no user challenge—used in the Face Liveness SDK and in Face Recognition’s Identify mode. **Active:** separate GitHub demos with smile/turn prompts (`Active-Liveness-Detection-Android` / `-iOS`); they are **not** the Face Liveness SDK. Face Liveness on Linux/Windows is still `POST /api/liveness` on one JPEG. ## Face Recognition liveness vs Face Liveness SDK? Identify on mobile includes **2D liveness** as part of matching. Standalone Face SDK **Liveness** is **anti-spoofing only** (no enroll / 1:N). See [Face SDK capabilities](/products/face-recognition-sdk/capabilities). ## Can face recognition work completely offline? Yes. After you activate with a license key bound to the app id (mobile) or machine code (server), matching does not need the internet. ## Can Faceplugin run on-premise? Yes. That is the product model: phone, Windows/Linux host, or Docker on **your** infrastructure. ## Does the Faceplugin SDK require an internet connection? Not for inference after activation. You need a network only to clone GitHub, pull Docker Hub, download Google Drive runtimes, and to contact Faceplugin for a license. ## Does Faceplugin support Flutter? Yes for Face Recognition and ID Document Recognition (`face_recognition_sdk`, `document_reader_sdk`). There is **no** public Face Liveness Flutter SDK — use Face Recognition’s 2D liveness on Identify and/or native Android/iOS Liveness. ## Does Faceplugin support iOS? Yes for Face Recognition, Face Liveness, and ID Document Recognition. Physical iPhone; demo bundle ids are listed on each iOS page. ## How many ID document types are supported? **16,900** templates across **255** countries and territories. Download the [Supported documents PDF](/products/id-document-recognition-sdk/capabilities#document-type-classification--worldwide-coverage). ## Docker vs host machine code `GET /api/machinecode` returns machine code. Docker and a native host on the same machine produce **different** codes. License the environment you run in production. See [Request a License](/help/request-a-license-and-support). ## Demo license key and my own app id Sample keys are bound to the **demo** application id / bundle id on the platform page. Request a new key for your production id. ## Match and liveness thresholds Mobile Identify default match **0.67**. Face Liveness server: score **≥ 0.5** → Real / pass. Change these defaults only if Faceplugin support gives you different recommended thresholds for your license. ## How large is the Android SDK? The GitHub repo is small. Native models (AAR + `.fpk` / engine) come from Google Drive and are large — that is why they are not on GitHub. Check the Google Drive folder size for the product you licensed. ## Is there a Node.js or C++ SDK? Document Reader has public Node / Go / C++ HTTP options. Face server integration is primarily HTTP (`curl` from any language) or Python `sdk.py` on the same host as `lib/cpu/`. See [Choose a product](/getting-started/choose-a-product). ## Where are acronyms defined? See the [Glossary](/help/resources/glossary) for MRZ, OCR, eKYC, 1:1 / 1:N, PAD, FRVT, license key, and machine code. ### Related documentation * [HTTP API](/integration/http-api) · [Deploy and host](/integration/deploy-and-host) * [Glossary](/help/resources/glossary) · [Try it](/getting-started/try-it) · [Troubleshooting](/help/resources/troubleshooting) · [Status codes](/help/resources/status-codes) * [Choose a product](/getting-started/choose-a-product) · [Passport OCR & ID verification](/help/resources/passport-ocr-and-id-verification) * [ID Document capabilities](/products/id-document-recognition-sdk/capabilities) · [Face SDK capabilities](/products/face-recognition-sdk/capabilities) * [SDK comparison](/help/comparisons) # Troubleshooting Troubleshoot Faceplugin SDK demos. Missing AAR or frameworks, wrong app id licenses, Docker shm-size, Yarn 3 on React Native, and cameras that stay black on emulators. Start here when a Faceplugin demo never reaches **Ready**, the camera stays black, or HTTP process calls fail after Docker starts. ## Home never shows Ready / tiles stay locked 1. Native runtime missing or nested in a subfolder. Check the exact AAR / framework path in that SDK's platform guide. 2. Wrong application id — demo license key only matches the sample id. 3. `init` returned 1–4. See [Status codes](/help/resources/status-codes). 4. Called activate/init on the UI thread (Android) or before the binary was packaged (hot reload is not enough). ## Camera black / crash Physical device, `CAMERA` permission / `NSCameraUsageDescription`, arm64. Document Reader and Face plugins often filter `arm64-v8a` only in the demo. ## Docker starts then process calls fail Activate with `POST /api/activate`. Detached Compose does not prompt. `--shm-size` too small for Document Reader (`dcr.fpk`). Privileged + machine-id volume as in the README. Sizing and Docker flags: [Hosting requirements](/integration/deploy-and-host/hosting-requirements). Endpoint contracts: [HTTP API](/integration/http-api). ## `lib/cpu` “file not found” You unzipped into `lib/cpu/FolderName/`. Files must sit **directly** in `cpu/`. ## React Native `npm install` broke the repo Use **Yarn 3** as `packageManager`. npm workspaces are not supported at the root. ## Ionic / Flutter in the browser `ionic serve` and Flutter web do not load the engine. Open Android Studio / Xcode after `cap sync` / `flutter run`. ## Two products in one APK / one `lib/` Do not dump a second product’s Google Drive runtime into another product’s `lib/cpu/`. Run separate servers instead. See [Architecture](/integration/deploy-and-host/architecture). ## Still stuck Email with: OS, GitHub repo name, activate/init code, and whether you used Docker or Google Drive. ### Related documentation * [HTTP API](/integration/http-api) · [Hosting requirements](/integration/deploy-and-host/hosting-requirements) · [Architecture](/integration/deploy-and-host/architecture) * [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) · [Status codes](/help/resources/status-codes) · [Try it](/getting-started/try-it) * [Request a License](/help/request-a-license-and-support) # Status codes Faceplugin SDK status codes for activate and init (0–4), Linux/Windows HTTP envelope codes, and document verification / image quality fields. Used across Face Recognition, Liveness, and Document SDKs. Use this page to decode **activate** and **init** results on mobile, HTTP envelope `code` values on Linux and Windows, and document verification fields in OCR JSON. ## Mobile activate / init Used by Android / iOS / Flutter / React Native / Ionic plugins: | Code | Constant | Meaning | | ---: | ---------------------------- | ------------------- | | 0 | `SDK_SUCCESS` / `sdkSuccess` | Activate or init OK | | 1 | `SDK_LICENSE_INVALID` | Invalid license | | 2 | `SDK_LICENSE_EXPIRED` | Expired | | 3 | `SDK_NOT_ACTIVATED` | Not activated | | 4 | `SDK_INIT_FAILED` | Init failed | Process methods typically return JSON strings (or typed objects). Serialize native calls. ## Document result codes (normalized JSON) | Field | 0 | 1 | 2 | | ---------------------- | ---- | ---- | ----------- | | Verification | Pass | Fail | Not checked | | Image QA `CheckResult` | Fail | Pass | Not checked | ## HTTP envelope (shared routes) | `code` | Typical meaning | | -----: | --------------------------------------------------------------- | | 0 | OK | | -1 | Empty or invalid license; missing required field on some routes | | -10 | Not found | | -19 | Unhandled server error | Process routes often **skip** the envelope and return engine JSON instead. ## Face Liveness server threshold Score **≥ 0.5** → Real / pass (product README). Change this default only if Faceplugin support gives you a different recommended threshold for your license. ### Related documentation * [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) · [Troubleshooting](/help/resources/troubleshooting) · [Request a License](/help/request-a-license-and-support) # Changelog Release history for Faceplugin Face Recognition, Face Liveness, and ID Document SDKs. Check each public GitHub repository and Docker Hub for the latest tags. Published release notes for Faceplugin SDKs will be listed here. ## Documentation * **HTTP API hub** — shared and per-product endpoint reference under [HTTP API](/integration/http-api) * **Deploy and host** — [Architecture](/integration/deploy-and-host/architecture), [Hosting requirements](/integration/deploy-and-host/hosting-requirements), [Production deployment](/integration/deploy-and-host/production-deployment) Until dated product release entries appear on this page, use: * The **Releases** tab on each [public GitHub repository](https://github.com/Faceplugin-ltd) * Docker Hub tags such as `latest` under [hub.docker.com/u/faceplugin](https://hub.docker.com/u/faceplugin) ### Related documentation * [Choose a product](/getting-started/choose-a-product) · [HTTP API](/integration/http-api) · [Deploy and host](/integration/deploy-and-host) * [Request a License](/help/request-a-license-and-support) · [Glossary](/help/resources/glossary) # SDK comparison On-premise face recognition and liveness SDK comparison. Faceplugin versus 3DiVi, FaceTec, and Luxand. Criteria from public vendor docs, not guessed checkmarks. This section compares **Faceplugin** to vendors people often evaluate for on-premise face matching, anti-spoofing (liveness), and ID reading. Tables use **public vendor documentation**. Where a fact is not stated on that vendor’s site, the cell is **Check vendor**. Faceplugin facts below match the products in these docs: on-premise/offline after license activation; Android, iOS, Flutter, React Native, Ionic, Windows, and Linux Docker; **passive** face anti-spoofing; passport OCR / ID card APIs (**16,900** templates / **255** countries — [catalog PDF](/products/id-document-recognition-sdk/capabilities#document-type-classification--worldwide-coverage)); document liveness on Linux; NIST FRVT **evaluated** matching. These docs do **not** claim iBeta certification for Face Liveness. Ask Faceplugin if you need a certification statement. Capability overviews: [ID Document SDK](/products/id-document-recognition-sdk/capabilities) · [Face SDK](/products/face-recognition-sdk/capabilities). | Page | When to read it | | ----------------------------------------------------- | ----------------------------------------------------- | | [Faceplugin vs 3DiVi](/help/comparisons/vs-3divi) | Cross-platform face SDK, C++ core, liveness estimator | | [Faceplugin vs FaceTec](/help/comparisons/vs-facetec) | 3D liveness / FaceMap KYC vs 2D on-prem SDK suite | | [Faceplugin vs Luxand](/help/comparisons/vs-luxand) | Classic FaceSDK vs Faceplugin + document products | Then integrate: [Document capabilities](/products/id-document-recognition-sdk/capabilities) · [Face Recognition Android](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) · [Liveness Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Document Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) ### Related documentation * [Choose a product](/getting-started/choose-a-product) · [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) # vs 3DiVi Faceplugin vs 3DiVi Face SDK. On-premise face recognition, platforms, liveness, and ID document products. Public 3DiVi docs versus Faceplugin products in these docs. [3DiVi Face SDK](https://3divi.ai/products/software/face-sdk) is a C++ face recognition library with wrappers (C#, Java, Python, Swift, Flutter) for Windows, Linux, Android, and iOS. It documents on-prem / on-device / own-cloud deployment and a **2d\_liveness** estimator. 3DiVi also sells OMNI Platform (client-server video) and Image API (REST). Faceplugin is an **on-premise SDK suite**: Face Recognition, standalone Face Liveness (passive anti-spoofing HTTP + mobile), ID Document Recognition (passport OCR / MRZ), and ID Document Liveness. **Server SDKs** are Docker Hub images licensed with a **machine code** (machine code). | Criterion | Faceplugin | 3DiVi | | ----------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------- | | On-premise / offline after license | Yes | Yes (offline and online license modes documented) | | Android / iOS face SDK | Yes | Yes | | Flutter face | Yes (Face Recognition + Document) | Yes (Face SDK docs list Flutter) | | React Native / Ionic | Yes | Check vendor | | Windows / Linux face | Yes (HTTP API + native) | Yes (C++/Python/C#) | | Linux Docker Hub HTTP API | Yes (`faceplugin/face-recognition`, `face-liveness`, `document-reader`) | Check vendor (local license server mentioned for Docker) | | Standalone face anti-spoofing product | Yes (passive `POST /api/liveness`) | Liveness as Face SDK estimator; BAF / other products exist | | Passport OCR / ID card SDK | Yes | Check vendor (not the core Face SDK page) | | Document liveness | Yes (Linux 8086) | Check vendor | | NIST FRVT (as claimed in Faceplugin docs) | Evaluated matching | Check vendor | | iBeta / PAD certification | No iBeta certification claimed in these docs — ask Faceplugin | Check vendor | | License model | Offline license key / machine code | Hardware, app id, USB token, online validation options | **Choose Faceplugin** when you want a **documented HTTP Docker API** plus **ID OCR and document liveness** in the same vendor docs, with mobile 1:N Identify demos. **Look at 3DiVi** when you need their C++ Face SDK / OMNI video platform specifically. Confirm Flutter / React Native and document OCR on [3DiVi docs](https://docs.3divi.ai/face_sdk/). Integrate Faceplugin: [Android Face Recognition](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) · [Liveness Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Document Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) ### Related documentation * [SDK comparison index](/help/comparisons) · [Choose a product](/getting-started/choose-a-product) · [Glossary](/help/resources/glossary) * [FAQ](/help/resources/faq) · [Try it](/getting-started/try-it) # vs FaceTec Faceplugin vs FaceTec. 2D on-premise face/liveness/document SDKs versus FaceTec 3D FaceMap liveness, server SDK, and usage-based 3D liveness billing. [FaceTec](https://www.facetec.com/) focuses on **3D liveness** (3D FaceMap / FaceScan), 3D face matching, and ID scan/OCR as part of that flow. Device SDKs target **iOS, Android, and webcams**. Customers run FaceTec **Server SDK** on their servers; FaceTec’s site describes **monthly 3D liveness usage** (minimum commitment) with ID scans included for customers. Certified PAD is a core FaceTec marketing claim. Faceplugin ships **2D** on-premise engines: still-image or camera-frame matching and **passive** anti-spoofing, plus standalone passport OCR and document liveness. Linux/Windows are **HTTP APIs** you host (ports 8083 / 8084 / 8082). License is an offline license key, not a per-liveness monthly meter in these docs. | Criterion | Faceplugin | FaceTec | | ------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------- | | On-premise processing | Yes (device or your HTTP host) | Yes (customer-hosted Server SDK; also cloud options) | | Offline after activation | Yes | Check vendor (3D session typically talks to **your** FaceTec server) | | Android / iOS | Yes | Yes | | Flutter / React Native / Ionic | Yes (FR + Document; Liveness is Android/iOS) | Check vendor | | Windows / Linux HTTP API | Yes | Server SDK / REST on **your** FaceTec server | | Passive 2D anti-spoofing | Yes | 3D liveness is the product | | Active / challenge liveness | Not the Face Liveness SDK | 3D video-selfie capture | | Passport OCR / ID scan | Yes (Document Recognition SDK) | Yes (Photo ID OCR / barcode / NFC per FaceTec site) | | Document liveness product | Yes (Linux) | ID tampering checks in Identity Check flow | | Flutter Face Liveness SDK | No public SDK | Check vendor | | Pricing model in public docs | License key / machine code | Monthly 3D liveness usage + minimums (per FaceTec.com) | | NIST / iBeta | NIST FRVT evaluated matching; no iBeta certification claimed in these docs | FaceTec publishes PAD certification claims — verify on FaceTec.com | **Choose Faceplugin** when you want **unlimited on-prem inference after license**, 2D JPEG/`faceDetection` APIs, Docker Hub images, and a **separate** document OCR engine you combine yourself ([eKYC](/getting-started/choose-a-product#combining-products-ekyc)). **Look at FaceTec** when you specifically need **3D FaceMap liveness** and their certified PAD / 3D matching stack. Integrate Faceplugin: [Android Face Recognition](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) · [Liveness Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Document Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) ### Related documentation * [SDK comparison index](/help/comparisons) · [Choose a product](/getting-started/choose-a-product) · [Glossary](/help/resources/glossary) * [FAQ](/help/resources/faq) · [Try it](/getting-started/try-it) # vs Luxand Faceplugin vs Luxand FaceSDK. On-premise face recognition and liveness versus Luxand’s FaceSDK library. Document OCR is Faceplugin-only in this table. [Luxand FaceSDK](https://www.luxand.com/facesdk/) is a long-running **on-premise face library** (Windows, Linux, macOS, iOS, Android, plus language bindings). It documents **passive and active** liveness and thermal-camera liveness. Luxand.cloud is a **separate cloud FaceAPI**. Public reviews describe FaceSDK as face matching/liveness **without** a document-verification product. Faceplugin adds a **document recognition** SDK (passport OCR, MRZ, barcode) and **document liveness**, plus Linux/Windows **HTTP Docker APIs** and Flutter / React Native / Ionic Face Recognition and Document plugins. | Criterion | Faceplugin | Luxand FaceSDK | | ------------------------------ | --------------------------------------------------------------------------------- | ------------------------------- | | On-premise / offline | Yes | Yes (FaceSDK; FaceAPI is cloud) | | Android / iOS | Yes | Yes | | Flutter / React Native / Ionic | Yes (FR + Document) | Check vendor | | Windows / Linux | Yes | Yes | | macOS SDK | Check vendor | Yes (FaceSDK site) | | Face recognition | Yes | Yes | | Passive liveness | Yes | Yes (documented) | | Active liveness | Public GitHub: Active-Liveness-Detection-Android / iOS. Not the Face Liveness SDK | Yes (Tracker API samples) | | Passport OCR / ID card SDK | Yes | No (public FaceSDK positioning) | | Document liveness | Yes | Check vendor | | HTTP Docker Hub images | Yes | Check vendor | | NIST FRVT | Evaluated matching (Faceplugin docs) | Check vendor | **Choose Faceplugin** when you need **ID document OCR + face + anti-spoofing** as documented products, or a **ready HTTP API** on Docker. **Look at Luxand** when you want a general-purpose FaceSDK (including macOS / thermal) and will add OCR from another vendor. Integrate Faceplugin: [Android Face Recognition](/products/face-recognition-sdk/recognition-and-liveness/mobile-sdk/face-recognition-android-sdk) · [Liveness Linux](/products/face-recognition-sdk/liveness-detection-sdk/server-sdk/liveness-detection-linux-sdk) · [Document Linux](/products/id-document-recognition-sdk/recognition-and-liveness/server-sdk/id-document-recognition-linux-sdk) ### Related documentation * [SDK comparison index](/help/comparisons) · [Choose a product](/getting-started/choose-a-product) · [Glossary](/help/resources/glossary) * [FAQ](/help/resources/faq) · [Try it](/getting-started/try-it) # Request a License & Support Request a Faceplugin offline license. Mobile license keys bind to app id. Server licenses start from a machine code from GET /api/machinecode. Docker and host codes differ. On-premise, no per-call clo Faceplugin licenses are **offline**. After activation, face matching, liveness, and document OCR do **not** need the internet. In short: **mobile** **license keys** bind to your app id; **server** licenses start from a **machine code** from the host or Docker you will run in production. Definitions: [Glossary](/help/resources/glossary). ### Need a license? * **Mobile SDK:** contact us via WhatsApp, Telegram, or email. Demo license keys are bound to the **sample application id / bundle id** on each platform page. Request a new license key if you use your own app. * **Server SDK (Linux / Windows / Docker):** start the API once, copy the **machine code** from logs or `GET /api/machinecode`, and send that code. Docker and a native host have **different** machine codes. Use the code from the environment you will run in production. Do not paste demo license keys into your production app. ### FAQ **Can Faceplugin run completely offline?** Yes, after the key is issued and activated. **Why is my Docker machine code different from the host?** The fingerprint includes Docker. License the environment you ship. **Status codes 1–4 on mobile?** See [Status codes](/help/resources/status-codes). ### Need support? Faceplugin provides integration help for licensed SDKs, plus ongoing support after you go live. Email, WhatsApp, or Telegram with your OS, GitHub repo name, activate/init result codes, and whether you use Docker or a native Google Drive runtime. ### Contact us * Email : * WhatsApp : [+1 (469) 278-4822](https://wa.me/+14692784822) * Telegram : [@FacePluginSupport](https://t.me/FacePluginSupport) ### Related documentation * [Try it](/getting-started/try-it) · [HTTP API shared endpoints](/integration/http-api/shared) · [Production deployment](/integration/deploy-and-host/production-deployment) * [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) · [Troubleshooting](/help/resources/troubleshooting) * [Choose a product](/getting-started/choose-a-product) · [Changelog](/help/resources/changelog) {% hint style="info" %} GitBook admin (not this markdown): custom domain, Open Graph image, sitemap, and **Google Search Console** on the docs hostname. {% endhint %} # Contact us Contact Faceplugin for licenses and integration support. Email, WhatsApp, and Telegram. Request mobile license keys or server machine codes for on-premise SDKs. Email, WhatsApp, or Telegram for licenses and integration help. * Email: * WhatsApp: [+1 (469) 278-4822](https://wa.me/+14692784822) * Telegram: [@FacePluginSupport](https://t.me/FacePluginSupport) ### Related documentation * [Request a License](/help/request-a-license-and-support) · [FAQ](/help/resources/faq) · [Glossary](/help/resources/glossary) * [Choose a product](/getting-started/choose-a-product) · [Try it](/getting-started/try-it)