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.
| Field | Type | Default | Description |
|---|---|---|---|
| imagerequired | file | — | 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
}| Field | Type | Description |
|---|---|---|
| success | boolean | Always true on a 200. |
| decision | string | live | 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_live | boolean | True 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. |
| score | float | null | Mean live probability across both checkpoints, 0-1. Null when the frame was not scored. |
| threshold | float | The value `score` was compared against. Returned so a verdict is checkable against the number that produced it. |
| face | object | null | Null when no face was detected. |
| face.bbox | int[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_score | float | Detector confidence for that face. |
| quality_flags | string[] | 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. |
| models | ModelScore[] | One entry per checkpoint, so a borderline mean can be traced to the two numbers behind it. |
| models[].name | string | The checkpoint that produced the score. |
| models[].live_score | float | That checkpoint's live probability. |
| models[].classes | integer | How many classes the checkpoint predicts. |
| models[].distribution | float[] | Raw softmax over those classes. Index 1 is live. |
| processing_time_ms | float | Model time. |