/v1/liveness_detection, /v1/deepfake_detection, /v1/unified_detection) accept the same image in four interchangeable forms. Pick whichever fits your stack.
Formats
- Multipart file
- Base64 JSON
- Image URL
- Raw bytes
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_boxcoordinates 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_BACKLITrather 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 plainthresholdapplies to both.
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 — passmin_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):
- Accuracy degrades with face size. Smaller faces are upscaled before scoring, and the further below the minimum they are, the less reliable
genuine_scorebecomes. Prefer fixing the capture when you can. - A face must still be detectable —
FACE_NOT_DETECTEDis unaffected by this flag.