Skip to main content
This endpoint accepts a single selfie image (Base64) and returns a liveness probability score plus face detection details. A liveness probability above 50 indicates that a real person was present; below that, the image may be a photo, print, or screen. Use the response to decide whether to allow the user to continue in your flow or to require a retry.

​
Request

[POST]
{{baseUrl}}/api/v1/ml/liveness/
HeaderTypeDescription
AppIdstringCreate an app to get your app ID on dashboard here
AuthorizationstringPrivate/secret key. Use <key> not Bearer <key>

​
Body parameter

ParameterTypeDescriptionRequired
imagestringImage format should be in Base64required
liveness_probability above 50 means liveness is confirmed.

​
Response

Response
{
    "entity":{
       "liveness": {
            "liveness_check": false,
            "liveness_probability": 0.014614949759561568
        },
        "face": {
            "face_detected": true,
            "message": "face detected",
            "multiface_detected": false,
            "details": {
                "age_range": {
                    "low": 25,
                    "high": 35
                },
                "smile": {
                    "value": false,
                    "confidence": 92.67727661132812
                },
                "gender": {
                    "value": "Female",
                    "confidence": 99.92608642578125
                },
                "eyeglasses": {
                    "value": false,
                    "confidence": 96.146484375
                },
                "sunglasses": {
                    "value": false,
                    "confidence": 99.99609375
                },
                "beard": {
                    "value": false,
                    "confidence": 85.18626403808594
                },
                "mustache": {
                    "value": false,
                    "confidence": 96.13561248779297
                },
                "eyes_open": {
                    "value": true,
                    "confidence": 88.61351776123047
                },
                "mouth_open": {
                    "value": false,
                    "confidence": 76.0062484741211
                },
                "emotions": [
                    {
                        "type": "CALM",
                        "confidence": 81.77631378173828
                    },
                    {
                        "type": "FEAR",
                        "confidence": 6.811796188354492
                    },
                    {
                        "type": "SURPRISED",
                        "confidence": 6.772216320037842
                    },
                    {
                        "type": "SAD",
                        "confidence": 6.691151142120361
                    },
                    {
                        "type": "ANGRY",
                        "confidence": 2.304255723953247
                    },
                    {
                        "type": "DISGUSTED",
                        "confidence": 2.147843599319458
                    },
                    {
                        "type": "HAPPY",
                        "confidence": 1.2251189947128296
                    },
                    {
                        "type": "CONFUSED",
                        "confidence": 0.9095264673233032
                    }
                ]
            },
            "quality": {
                "brightness": 65.93645477294922,
                "sharpness": 97.45164489746094
            },
            "confidence": 99.99896240234375,
            "bounding_box": {
                "width": 0.4954420328140259,
                "height": 0.39241859316825867,
                "left": 0.27790528535842896,
                "top": 0.3333175778388977
            }
        }
    }
}

​
Response Fields

FieldTypeDescription
entityobjectContains the response data
entity.livenessobjectLiveness detection results
entity.liveness.liveness_checkbooleanWhether the face passed the liveness check (true if liveness_probability > 50)
entity.liveness.liveness_probabilitynumberProbability score (0–100) that the image contains a live person. Values above 50 indicate a real person; below 50 suggests a photo, print, or screen
entity.faceobjectFace detection results and attributes
entity.face.face_detectedbooleanWhether a face was detected in the image
entity.face.messagestringHuman-readable face detection status message
entity.face.multiface_detectedbooleanWhether multiple faces were detected in the image
entity.face.detailsobjectDetailed face attributes extracted from the image
entity.face.details.age_rangeobjectEstimated age range of the detected face
entity.face.details.age_range.lowintegerLower bound of the estimated age
entity.face.details.age_range.highintegerUpper bound of the estimated age
entity.face.details.smileobjectSmile detection result
entity.face.details.smile.valuebooleanWhether the person is smiling
entity.face.details.smile.confidencenumberConfidence score (0–100) for the smile detection
entity.face.details.genderobjectGender classification result
entity.face.details.gender.valuestringDetected gender (e.g., Male, Female)
entity.face.details.gender.confidencenumberConfidence score (0–100) for the gender classification
entity.face.details.eyeglassesobjectEyeglasses detection result
entity.face.details.eyeglasses.valuebooleanWhether the person is wearing eyeglasses
entity.face.details.eyeglasses.confidencenumberConfidence score (0–100) for eyeglasses detection
entity.face.details.sunglassesobjectSunglasses detection result
entity.face.details.sunglasses.valuebooleanWhether the person is wearing sunglasses
entity.face.details.sunglasses.confidencenumberConfidence score (0–100) for sunglasses detection
entity.face.details.beardobjectBeard detection result
entity.face.details.beard.valuebooleanWhether the person has a beard
entity.face.details.beard.confidencenumberConfidence score (0–100) for beard detection
entity.face.details.mustacheobjectMustache detection result
entity.face.details.mustache.valuebooleanWhether the person has a mustache
entity.face.details.mustache.confidencenumberConfidence score (0–100) for mustache detection
entity.face.details.eyes_openobjectEyes open detection result
entity.face.details.eyes_open.valuebooleanWhether the person’s eyes are open
entity.face.details.eyes_open.confidencenumberConfidence score (0–100) for eyes open detection
entity.face.details.mouth_openobjectMouth open detection result
entity.face.details.mouth_open.valuebooleanWhether the person’s mouth is open
entity.face.details.mouth_open.confidencenumberConfidence score (0–100) for mouth open detection
entity.face.details.emotionsarrayList of detected emotions ranked by confidence
entity.face.details.emotions[].typestringEmotion type (e.g., CALM, HAPPY, SAD, ANGRY, SURPRISED, DISGUSTED, FEAR, CONFUSED)
entity.face.details.emotions[].confidencenumberConfidence score (0–100) for the detected emotion
entity.face.qualityobjectImage quality metrics for the detected face
entity.face.quality.brightnessnumberBrightness score (0–100) of the face region
entity.face.quality.sharpnessnumberSharpness score (0–100) of the face region
entity.face.confidencenumberOverall confidence score (0–100) that a face is present in the image
entity.face.bounding_boxobjectCoordinates of the face bounding box as proportions of the image dimensions
entity.face.bounding_box.widthnumberWidth of the bounding box as a ratio (0–1) of the image width
entity.face.bounding_box.heightnumberHeight of the bounding box as a ratio (0–1) of the image height
entity.face.bounding_box.leftnumberLeft edge position as a ratio (0–1) from the left side of the image
entity.face.bounding_box.topnumberTop edge position as a ratio (0–1) from the top of the image