API Documentation
Everything you need to integrate FaceGuard into your application.
Introduction
FaceGuard is a REST API that provides face recognition, liveness detection, and facial analysis. All endpoints accept multipart/form-data image uploads and return structured JSON.
High Performance
Sub-second response times. All models run in parallel.
Simple Auth
One API key header. No OAuth, no tokens to refresh.
Zero Retention
Images processed in memory and immediately discarded.
Base URL: https://api.faceguard.io
🔑 Authentication
All API requests require your API key in the X-API-Key request header.
⚠ Security Warning
Never expose API keys in client-side code, mobile apps, or public repositories. Always proxy requests through your own backend server.
Manage your API keys from your FaceGuard dashboard. Test keys are prefixed fg_test_ and limited to 50 requests.
⚡ Quickstart
Make your first API call in under 2 minutes. This example checks if a person is live and not a spoof.
curl -X POST https://api.faceguard.io/api/v1/liveness/check \ -H "X-API-Key: fg_live_your_key_here" \ -F "file=@selfie.jpg"
{
"is_live": true,
"confidence": 0.97,
"spoof_type": null,
"processing_time_ms": 420
}⚡ Performance Tips
Response time is directly affected by image file size. Images under 500KB consistently respond within 1–2 seconds.
| Image Size | Typical Response | Recommendation |
|---|---|---|
| < 500 KB | ~1–2s | ✓ Optimal |
| 500 KB – 1 MB | ~2–4s | ⚠ Consider compressing |
| > 1 MB | 4s+ | ✗ Not recommended |
⚠ Error Handling
FaceGuard uses standard HTTP status codes. All errors return a JSON body with detail containing the error information.
| Code | Message | Reason |
|---|---|---|
| 400 | Bad Request | Missing file or invalid parameters |
| 401 | Unauthorized | Missing or invalid API key |
| 422 | Unprocessable | No face detected in the image |
| 429 | Too Many Requests | Monthly request limit reached |
| 500 | Server Error | Internal processing error |
GET /api/v1/health
Check that the FaceGuard API is online and responding. No API key required.
curl https://api.faceguard.io/api/v1/health
{ "status": "ok", "version": "1.0.0" }POST /api/v1/liveness/check
Determine whether a face in an image is from a live person or a spoof attack. Fuses ONNX MiniFASNet and DeepFace with majority voting.
Parameters
filemultipart/form-data — face image (JPG, PNG, WebP)curl -X POST https://api.faceguard.io/api/v1/liveness/check \ -H "X-API-Key: fg_live_your_key_here" \ -F "file=@face.jpg"
{
"is_live": true,
"confidence": 0.97,
"spoof_type": null,
"models": {
"onnx": { "is_live": true, "score": 0.96 },
"deepface": { "is_live": true, "score": 0.98 }
},
"processing_time_ms": 420
}POST /api/v1/face/detect
Detect face presence and bounding boxes in an image.
curl -X POST https://api.faceguard.io/api/v1/face/detect \ -H "X-API-Key: fg_live_your_key_here" \ -F "file=@image.jpg"
{
"faces_detected": 1,
"faces": [{ "bbox": [120, 80, 280, 320], "confidence": 0.99 }]
}POST /api/v1/face/verify
Compare two face images. Returns a verified/not-verified decision based on 4-model majority voting.
curl -X POST https://api.faceguard.io/api/v1/face/verify \ -H "X-API-Key: fg_live_your_key_here" \ -F "file1=@person_a.jpg" \ -F "file2=@person_b.jpg"
{
"verified": true,
"confidence": 0.91,
"models": {
"ArcFace": { "verified": true, "distance": 0.28 },
"Facenet512": { "verified": true, "distance": 0.35 },
"buffalo_l": { "verified": true, "distance": 0.31 },
"buffalo_sc": { "verified": false, "distance": 0.42 }
}
}POST /api/v1/face/similarity
Return a similarity score (0–1) between two faces without a binary verdict.
curl -X POST https://api.faceguard.io/api/v1/face/similarity \ -H "X-API-Key: fg_live_your_key_here" \ -F "file1=@a.jpg" \ -F "file2=@b.jpg"
{ "similarity": 0.84, "distance": 0.29, "threshold": 0.40 }POST /api/v1/face/analyze
Extract age, gender, dominant emotion, and ethnicity from a single face image.
curl -X POST https://api.faceguard.io/api/v1/face/analyze \ -H "X-API-Key: fg_live_your_key_here" \ -F "file=@face.jpg"
{
"age": 28,
"gender": { "value": "Man", "confidence": 0.94 },
"emotion": { "dominant": "happy", "scores": { "happy": 0.87, "neutral": 0.10 } },
"ethnicity": { "dominant": "asian", "confidence": 0.76 }
}POST /api/v1/face/enroll
Extract and return base64-encoded face embedding vectors for a user.
curl -X POST https://api.faceguard.io/api/v1/face/enroll \ -H "X-API-Key: fg_live_your_key_here" \ -F "file=@user_photo.jpg" \ -F "user_id=emp_001"
{
"user_id": "emp_001",
"embeddings": {
"ArcFace": "base64_encoded_vector...",
"buffalo_l": "base64_encoded_vector..."
},
"face_detected": true
}POST /api/v1/face/identify
Match a probe face against a list of enrolled users.
curl -X POST https://api.faceguard.io/api/v1/face/identify \
-H "X-API-Key: fg_live_your_key_here" \
-F "file=@probe.jpg" \
-F 'candidates=[{"user_id":"emp_001","embeddings":{"ArcFace":"...","buffalo_l":"..."}}]'{
"matched": true,
"best_match": { "user_id": "emp_001", "distance": 0.29, "threshold": 0.40 }
}POST /api/v1/face/search
Search for a probe face across a gallery of images.
curl -X POST https://api.faceguard.io/api/v1/face/search \ -H "X-API-Key: fg_live_your_key_here" \ -F "query=@probe.jpg" \ -F "gallery=@person1.jpg" \ -F "gallery=@person2.jpg"
{
"matches": [
{ "filename": "person1.jpg", "distance": 0.24, "matched": true },
{ "filename": "person2.jpg", "distance": 0.61, "matched": false }
]
}POST /api/v1/face/embeddings
Extract raw embedding vectors without enrolling a user.
curl -X POST https://api.faceguard.io/api/v1/face/embeddings \ -H "X-API-Key: fg_live_your_key_here" \ -F "file=@face.jpg"
{
"embeddings": {
"ArcFace": "base64_encoded_vector...",
"buffalo_l": "base64_encoded_vector..."
},
"face_detected": true
}