FR-APIaaS - Face Recognition API as a Service

Liveness detection prevents spoofing attacks where a bad actor attempts to fool the system using a photo, video playback, or 3D mask instead of a real person's face. The check runs automatically on every enrollment by default.

Passive vs. active liveness

Automatic

Passive (default)

✓Single photo analysis
✓Neural anti-spoofing model
✓Runs on every enrollment
✓No user interaction needed
✓~15ms overhead per request

Interactive

Active (optional)

✓Requires user action
✓Blink or head-turn prompt
✓Video frame analysis
✓Higher anti-spoof confidence
✓Implemented client-side

Standalone liveness check

Run a liveness check without enrolling a face. Useful for verifying a selfie before proceeding with registration in your own flow.

curl -X POST https://your-domain.com/api/v1/collections/COLLECTION_ID/liveness \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "image=@selfie.jpg"

{
  "success": true,
  "data": {
    "is_live": true,
    "liveness_score": 0.97,
    "spoof_type": null,
    "query_time_ms": 15
  }
}

Liveness during enrollment

Liveness runs automatically during face enrollment. To skip it (not recommended for production), pass check_liveness=false:

POST /api/v1/collections/{collection_id}/faces
X-API-Key: fr_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: multipart/form-data

image=@photo.jpg
external_id=user_123
check_liveness=false   # not recommended

Response fields

Field	Type	Description
is_live	boolean	true if the face passes the liveness threshold (≥ 0.6).
liveness_score	float	Anti-spoof confidence, 0.0–1.0. Higher = more likely real.
spoof_type	string \| null	Detected spoof type: "print", "replay", "3d_mask", or null.
query_time_ms	integer	Time taken for liveness analysis (ms).

Liveness threshold

The default liveness threshold is 0.6. Enrollments with a score below this threshold are rejected with LIVENESS_CHECK_FAILED. You can adjust the threshold per-request for standalone checks:

image=@selfie.jpg
liveness_threshold=0.75   # stricter liveness requirement

Try it live

Upload any face photo to test the liveness detection endpoint against your collection.

Try it livePOST/collections/{collection_id}/liveness

Parameters

image*(file)

The image to check for liveness

Click to upload: JPG, PNG, WebP

Spoof types detected

print: Printed photo or displayed on a screen held flat.
replay: Video played on a phone or tablet screen.
3d_mask: 3D-printed or sculpted facial mask.

The liveness engine achieves >96% detection accuracy across print and replay attack categories in independent benchmarks.