API Documentation
Everything you need to integrate FaceGuard into your application.
Introduction
FaceGuard is a REST API for face recognition, liveness detection, and facial analysis. All endpoints accept multipart/form-data image uploads and return JSON.
High Performance
Sub-second response. All models run in parallel.
Simple Auth
One API key header. No OAuth or token refresh.
Zero Retention
Images processed in memory, immediately discarded.
Base URL: https://engine.faceguard.codelyticalhub.com
π Authentication
Send your API key in the X-API-Key request header on every request.
β Note
Manage keys from your dashboard. Test keys are prefixed fg_test_ and capped at 50 requests.
β‘ Quickstart
Make your first API call in under 2 minutes.
β‘ Performance Tips
Images under 500 KB consistently respond within 1β2 seconds.
β Error Handling
All errors return JSON with a detail field.
GET /api/v1/health
Check API availability. No key required.
POST /api/v1/liveness/check
Detect whether the face is live or spoofed. Fuses ONNX MiniFASNet + DeepFace with majority voting.
POST /api/v1/face/detect
Detect face presence and bounding boxes.
POST /api/v1/face/verify
Compare two face images. Returns a majority-vote decision across 4 models.
POST /api/v1/face/similarity
Return a 0β1 similarity score between two faces without a binary verdict.
POST /api/v1/face/analyze
Extract age, gender, dominant emotion, and ethnicity.
POST /api/v1/face/enroll
Extract and return base64 embeddings for a user. Store these in your database.
POST /api/v1/face/identify
Match a probe face against a list of enrolled users.
POST /api/v1/face/search
Search a probe face across a gallery of images.
POST /api/v1/face/embeddings
Extract raw embedding vectors without enrolling a user.
Mobile SDKs
Native SDKs for Android and iOS β capture faces and scan identity documents directly in your mobile app, no server required for on-device capture.
Face Capture SDK
On-device face detection and capture SDK. Use it to capture a clean face image in your mobile app and pass it to any FaceGuard API endpoint. No API key or network connection required for the capture itself.
Installation
Add to build.gradle.kts:
Permissions
βΉ Info
Quick Start
Configuration
Complete example app
β Note
Liveness SDK
On-device liveness detection powered by ncnn and the Silent-Face-Anti-Spoofing (MiniFASNet) model ensemble β the same detection engine on both platforms. Distinguishes a live person from a photo, screen replay, or mask; face data never leaves the device during detection, and screen/print replays are additionally flagged via ML Kit Image Labeling (Android) or Vision (iOS).
Installation
Permissions
βΉ Info
CAMERA, INTERNET and ACCESS_NETWORK_STATE in its own manifest and they merge automatically into your app β INTERNET is only used for API key validation on first launch, detection itself runs entirely on-device.Quick Start
Result types
Configuration
Pass a LivenessConfig to start() to override any of these β all have sensible defaults:
Complete example app
GhanaCard SDK
Automatic Ghana Card (ECOWAS Identity Card) scanning SDK. Detects and captures both sides of the card, extracts all fields including MRZ and the passport photo β entirely on-device.
Installation
Permissions
β Note
withCamera() before calling GhanaCardSDK.scan().