Skip to main content
The three detection endpoints (/v1/liveness_detection, /v1/deepfake_detection, /v1/unified_detection) accept the same image in four interchangeable forms. Pick whichever fits your stack.

Formats

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

Requirements and behavior

  • Formats: JPEG, PNG, WebP, GIF, BMP — anything a standard image decoder reads. HEIC isn’t supported, so convert iPhone photos to JPEG or PNG. Undecodable input returns 422 INVALID_IMAGE.
  • Size limit: 10 MB, enforced on the decoded payload and on URL downloads alike (413 IMAGE_TOO_LARGE).
  • Orientation: liveness applies EXIF rotation automatically. Deepfake detection scores the file exactly as sent, so face_box coordinates refer to the unrotated pixels.
  • One clear face (liveness and unified): the image must contain a detectable face, and its bounding box must be at least 128×128 pixels (422 FACE_NOT_DETECTED / FACE_TOO_SMALL). The error message reports the detected size, e.g. Detected face 110x104 smaller than minimum 128x128. In practice, any uncropped selfie from a modern phone camera clears this comfortably — it matters when faces are small in the frame or images were downscaled. If your capture flow can’t guarantee close-up faces, you can turn this gate off per request.
  • Lighting: heavily backlit captures are rejected with 422 IMAGE_BACKLIT rather than scored unreliably — prompt the user to retake with light on the face.
  • Deepfake detection needs an image of at least 512×512 pixels, but no face. A smaller image returns 422 IMAGE_TOO_SMALL (e.g. Image 480x640 smaller than minimum 512x512) and isn’t charged. A photo without a usable face (none found, or under 64 px) is still checked for AI generation, and the response says the face check was skipped. See Deepfake signals.
Don’t downscale, re-encode or rotate before sending. Deepfake detection reads fine pixel-level traces that resizing and re-compression destroy — send the original file. 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: threshold — a number in [0, 1].
  • Unified: thresholds — an object like {"face_liveness": 0.6, "deepfake": 0.4} (JSON body only). A plain threshold applies to both.
Invalid values return 400 INVALID_THRESHOLD. See Thresholds & scores for when to override.

Disabling the minimum face size gate

If your images legitimately contain smaller faces — CCTV frames, wide-angle kiosks, archived photos — pass min_face_check: false (JSON body or multipart field) to skip liveness’s 128×128 gate and score the image anyway (deepfake detection has no face size gate; its 512×512 minimum image size always applies):
Two things to know before you turn it off:
  • Accuracy degrades with face size. Smaller faces are upscaled before scoring, and the further below the minimum they are, the less reliable genuine_score becomes. Prefer fixing the capture when you can.
  • A face must still be detectable — FACE_NOT_DETECTED is unaffected by this flag.
The flag applies to the single-product and unified endpoints. Verification sessions (SDK flow) always keep the gate on: the capture UI controls framing, so small faces there indicate a capture problem, not a use case.