API reference

Check face liveness

Score one frame for a presentation attack — print, screen replay or flat mask.

POST /v1/face-liveness/check1 operation per image

The programmatic form of Face Liveness in the dashboard — same models, same allowance.

Request

multipart/form-data, with your key as a bearer token.

FieldTypeDefaultDescription
imagerequiredfile—JPEG or PNG. A single frame — a still, or one frame taken from a video.

Example

curl -X POST https://api.quantilence.com/v1/face-liveness/check \
  -H "Authorization: Bearer $QUANTILENCE_API_KEY" \
  -F "image=@photo.jpg"

Response

200 OK with this shape. Values below are illustrative; the keys and types are not.

{
  "success": true,
  "decision": "spoof",
  "is_live": false,
  "score": 0.214,
  "threshold": 0.82,
  "face": {
    "bbox": [
      212,
      96,
      268,
      268
    ],
    "detection_score": 0.99
  },
  "quality_flags": [],
  "models": [
    {
      "name": "2.7_80x80_MiniFASNetV2",
      "classes": 3,
      "live_score": 0.188,
      "distribution": [
        0.761,
        0.188,
        0.051
      ]
    },
    {
      "name": "4_0_0_80x80_MiniFASNetV1SE",
      "classes": 3,
      "live_score": 0.24,
      "distribution": [
        0.702,
        0.24,
        0.058
      ]
    }
  ],
  "processing_time_ms": 84.2
}
FieldTypeDescription
successbooleanAlways true on a 200.
decisionstringlive | spoof | no_face | low_quality. Only `live` is a pass. `no_face` and `low_quality` are refusals to score, not soft failures — treat them as 'ask for another frame', not as 'rejected'.
is_livebooleanTrue only when decision is `live`. Never true on any failure path, including when the models are unreachable — that is a 503, not a permissive default.
scorefloat | nullMean live probability across both checkpoints, 0-1. Null when the frame was not scored.
thresholdfloatThe value `score` was compared against. Returned so a verdict is checkable against the number that produced it.
faceobject | nullNull when no face was detected.
face.bboxint[4][x, y, width, height] in pixels — note this is width/height, not the [x1,y1,x2,y2] the other face endpoints return.
face.detection_scorefloatDetector confidence for that face.
quality_flagsstring[]Why a frame was refused rather than scored: too_blurry, too_dark, too_bright, face_too_far, face_too_close, face_too_small. Empty when it was scored.
modelsModelScore[]One entry per checkpoint, so a borderline mean can be traced to the two numbers behind it.
models[].namestringThe checkpoint that produced the score.
models[].live_scorefloatThat checkpoint's live probability.
models[].classesintegerHow many classes the checkpoint predicts.
models[].distributionfloat[]Raw softmax over those classes. Index 1 is live.
processing_time_msfloatModel time.