SpoofSense Image Input Formats: File, Base64, URL, and Bytes

The three detection endpoints — POST /v1/liveness_detection, POST /v1/deepfake_detection, and POST /v1/unified_detection — accept the same image in four interchangeable forms. Pick whichever fits your stack; the server treats them identically once decoded.

Formats

Multipart file
Base64 JSON
Image URL
Raw bytes

curl -X POST https://api.spoofsense.ai/v1/liveness_detection \
  -H "Authorization: Bearer $SPOOFSENSE_API_KEY" \
  -F "file=@selfie.jpg" \
  -F "threshold=0.6"

The field name file is canonical; image is accepted as an alias.

curl -X POST https://api.spoofsense.ai/v1/liveness_detection \
  -H "Authorization: Bearer $SPOOFSENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data": "'"$(base64 -i selfie.jpg)"'"}'

data accepts plain base64 or a full data URL (data:image/jpeg;base64,…). image is accepted as an alias for data.

curl -X POST https://api.spoofsense.ai/v1/liveness_detection \
  -H "Authorization: Bearer $SPOOFSENSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/selfie.jpg"}'

SpoofSense fetches the URL server-side (http/https only, 10-second timeout). url is accepted as an alias for image_url.

curl -X POST https://api.spoofsense.ai/v1/liveness_detection \
  -H "Authorization: Bearer $SPOOFSENSE_API_KEY" \
  -H "Content-Type: image/jpeg" \
  --data-binary @selfie.jpg

Any request body that isn’t JSON or multipart is treated as raw image bytes.

Requirements and behavior

Formats: JPEG, PNG, WebP, GIF, BMP — anything a standard image decoder reads. Undecodable input returns 422 INVALID_IMAGE.
Size limit: 10 MB, enforced on the decoded payload and on URL downloads alike. Requests over the limit return 413 IMAGE_TOO_LARGE.
Orientation: EXIF rotation is applied automatically before detection, so portrait captures from phones are always analyzed correctly.
One clear face: the image must contain a detectable face, large enough to analyze. Missing or distant faces return 422 FACE_NOT_DETECTED or 422 FACE_TOO_SMALL.
Lighting: heavily backlit captures are rejected with 422 IMAGE_BACKLIT rather than scored unreliably — prompt the user to retake with light on the face, not behind it.

Don’t downscale or re-encode before sending. Resolution is load-bearing for deepfake detection — send the original capture. Failed input validation (any 4xx) is never charged.

Threshold overrides

All input forms accept an optional per-request threshold (JSON body or multipart field):

Single endpoints (/v1/liveness_detection, /v1/deepfake_detection): use the threshold field — a number in [0, 1].
Unified endpoint (/v1/unified_detection): use the thresholds object, e.g. {"face_liveness": 0.6, "deepfake": 0.4} (JSON body only). A plain threshold applies to both checks.

Invalid values return 400 INVALID_THRESHOLD. See Thresholds & scores for when and how to tune.

Get Started

Guides

Verification Sessions

SpoofSense Image Input Formats: File, Base64, URL, and Bytes

Formats

Requirements and behavior

Threshold overrides

​Formats

​Requirements and behavior

​Threshold overrides

Formats

Requirements and behavior

Threshold overrides