Describe

This API returns liveness detection results. You can use biz_id as the index to search for the FaceID H5 verification results. The results are only stored for one day and can only be obtained through this API 3 times. If you call this API to obtain the results the 4th time or the results have expired, an error is returned. Make sure you obtain the data for each service before it expires.

Call URL

Singapore:
https://api-sgp.megvii.com/faceid/lite/raw/get_result

Note:
In production environments, always use HTTPS communication.
HTTP is insecure and poses security risks. Using HTTP in production will void service reliability guarantees.

Calling Method

GET

Parameters

Required/Optional	Parameter	Type	Description
Required	api_key	String	API key for calling this API
Required	api_secret	String	Secret of the api_key
Required	token	String	Tokens returned by get_token
Optional	return_image	String	Determines whether to return best quality images: `0` (default): No image `1`: Return 1 best quality image `2`: Return 2 best quality images

Return Value Description

Parameter	Type	Description
request_id	String	API call serial number Example: `"1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c"`
biz_no	String	Customer business serial number (returned only if set during call, matches input value exactly)
time_used	Int	Total request time in milliseconds (always returned)
status	String	Possible values: - `NOT_STARTED`: Live detection not started - `PROCESSING`: Verification in progress - `OK`: Verification completed - `FAILED`: Live detection failed
liveness_result	Json	Live detection result; if the user interrupts the live process midway, this field will not be returned result: The result of live detection. Possible values: - `PASS`: Live detection passed. - `FAIL`: Live detection failed. details: Details of the live detection result. This object records the number of times various issues occurred during the process. Note: The presence of these issues does not necessarily mean the overall result is `FAIL`. The details object contains the following keys (each key maps to a count of occurrences): - `FACE_NOT_FOUND`: Number of times no face was detected. - `SIDE_FACE`: Number of times the face was not facing the camera directly (side face). - `UPDOWN_FACE`: Number of times the face was not facing the camera directly (looking up or down). - `EYE_OCCLUSION`: Number of eye occlusions. - `MOUTH_OCCLUSION`: Number of mouth occlusions. - `AWAY_FROM_CAMERA`: Number of times the face was too far from the camera. - `CLOSE_TO_CAMERA`: Number of times the face was too close to the camera. - `FACE_OUT_OF_CAMERA`: Number of times the face was not facing the camera directly. - `HIGH_BRIGHTNESS`: Number of times the ambient light was too bright. - `LOW_BRIGHTNESS`: Number of times the ambient light was too dim. - `LOW_FACE_QUALITY`: Number of times the face quality in the video was too poor. score: Score of flash sensor face ID live detection. flash_attack: Flash attack score, reflecting the degree of inconsistency between the lighting color sequence of the uploaded video stream and the sequence issued by the system. living_attack: Living attack score, indicating the credibility that the user is an attacker.
verify_result	Json	Face comparing result; if the user interrupts the live detection process midway, this field will not be returned - error_message: An error occurred during face comparing: - `null`: indicates that no error has occurred - `NO_FACE_FOUND`: : No face was detected in the image - `DATA_SOURCE_ERROR`: An error occurred while calling the comparison data, generally indicating a data error. When this error occurs, it is recommended to stop the business and immediately contact FaceID customer service or business personnel. Resume the business after confirmation. - `INTERNAL_ERROR`: Internal server error. When such an error occurs, please make another request. If this error persists, please contact FaceID customer service or business personnel promptly. result_ref[x]: Comparison result between the live-captured portrait and the uploaded image_ref[x]; - "confidence": Confidence Level of the composite score, of Float type, with a value range of [0, 100], where a larger number indicates lower risk. - "thresholds": A set of confidence level thresholds for reference, of Object type, containing four fields, all of Float type with values in the range [0, 100]: - "1e-3": Confidence Level Threshold for a One-in-a-Thousand Risk - "1e-4": Confidence Level Threshold for a One-in-Ten-Thousand Risk - "1e-5": Confidence Level Threshold for a Risk of One in One Hundred Thousand - "1e-6": Confidence Level Threshold for a One-in-a-Million Risk
image_best	String	This field is only returned when the call is successful and the return_image field is configured as 1 or 2, and the returned value will be the highest quality face photo from the video used for face comparing. It is returned as a Base64 string, with the image format being JPEG. In exceptional cases, this field may return null.
image_best_2	String	This field is only returned when the call is successful and the return_image field is configured to 2, returning another live image with the best quality. It is returned as a Base64 string, and the image format is JPEG. In exceptional cases (such as when only one image meets the quality criteria), this field may return null.

Return Examples

When status is "OK":

{
  "request_id": "1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c",
  "biz_no": "your_biz_no",
  "time_used": 100,
  "status": "OK",
  "liveness_result": {
    "score":{
        "flash_attack":0.5,
        "living_attack":0.5
    },
    "result":0.5,
    "details":0.5
    },
    "request_id":"1629684531,ec2fc2a6-01fc-4ecf-82fe-f26c5bf1b2ed",
    "verify_result":
    {
    "result_faceid": {
            "confidence": 68.918,
            "thresholds": {
                "1e-3": 64,
                "1e-4": 69,
                "1e-5": 74,
                "1e-6": 79.9
            }
        },
    "result_ref1": {
        "confidence": 68.918,
        "thresholds": {
            "1e-3": 64,
            "1e-4": 69,
            "1e-5": 74,
            "1e-6": 79.9
        }
    },
    "result_idcard_photo": {
        "confidence": 68.918,
        "thresholds": {
            "1e-3": 64,
            "1e-4": 69,
            "1e-5": 74,
            "1e-6": 79.9
        }
    },
    "result_idcard_datasource": {
        "confidence": 68.918,
        "thresholds": {
            "1e-3": 64,
            "1e-4": 69,
            "1e-5": 74,
            "1e-6": 79.9
        }
    },
    "biz_no":"c22fe4e0-66ba-4078-bd9b-3b1a20628f8d"
}

When status is "Failed":

{
    "status": "Failed",
    "time_used":2,
    "image_best":"data:image/jpeg;base64,",
    "liveness_result":{
        "score":{
            "flash_attack":0.5,
            "living_attack":0.5
        },
        "result":0.5,
        "details":0.5
    },
    "request_id":"1629684531,ec2fc2a6-01fc-4ecf-82fe-f26c5bf1b2ed",
    "verify_result":{
    
    },
    "biz_no":"c22fe4e0-66ba-4078-bd9b-3b1a20628f8d"
}

When status is "NOT_STARTED":

{
    "status": "NOT_STARTED",
    "time_used":2,
    "image_best":"data:image/jpeg;base64,",
    "liveness_result":{
        "score":{
            "flash_attack":null,
            "living_attack":null
            },
        "result":null,
        "details":null
    },
    "request_id":"1629684531,ec2fc2a6-01fc-4ecf-82fe-f26c5bf1b2ed",
    "verify_result":{
    
    },
    "biz_no":"c22fe4e0-66ba-4078-bd9b-3b1a20628f8d"
}

Error Code List

GetResult Specific Errors

HTTP Status Code	Error Message	Description
400	RESULT_NOT_FOUND	Incorrect business number provided

Universal Errors

HTTP Status Code	Error Message	Description
403	AUTHENTICATION_ERROR	Invalid signature
403	AUTHORIZATION_ERROR:	API key deactivated, call limit exceeded, or insufficient permissions Example: Denied (no API permission)
403	CONCURRENCY_LIMIT_EXCEEDED	Concurrency exceeds limit
400	MISSING_ARGUMENTS:	Missing required parameter
403	DATA_DESTROYED	Exceeded queryable time or max query count
400	BAD_ARGUMENTS:	Parameter parsing error (e.g., invalid type/length)
404	API_NOT_FOUND	Called API does not exist
500	INTERNAL_ERROR	Internal server error (retry request or contact support)