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

Indonesia region ：https://api-idn.megvii.com/faceid/lite/get_result

Note : Please use HTTPS in production environments. HTTP communication is not secure, poses risks, and is not recommended for production environments. If you use HTTP in production environments, service reliability cannot be guaranteed.

Call method

Get

Permissions

Only when the user accesses the FaceID product can the FaceID Web APIs be called. Please consult FaceID business personnel for the process of accessing FaceID.

Parameter

Required/optional	parameter	type	Parameter Description
Required	api_key	String	The api_key used to call this API.
Required	api_secret	String	The secret of the api_key used to call this API.
Required	biz_no	String	The serial number of the customer business. The value of this parameter must be unique. This number is returned to your server in notify and return to help you confirm business relationships. The length of the value cannot exceed 128 bytes.
Optional	return_verify_time	String	This parameter specifies whether to return the verification time. Valid values include 0: Do not return the verification time; 1: Return the verification time.
Optional	return_image	String	This parameter is optional and specifies whether to return the image data of the liveness detection. Valid values: 0: Do not return image (default). 1: Return the best-quality image (image_best).

Return value description

Parameter	Type	Description	Example
request_id	String	The serial number of the API call.	"1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c"
status	String	The status of FaceID Lite. Valid values: • NOT_STARTED: The do method is not called after get_token. The verification is not started. • PROCESSING: The FaceID Lite verification is in progress. • WEBRTC_UNSUPPORTED: This indicates that the browser is not supported, which leads to a failed verification. •OK: The FaceID Lite verification is completed (OK indicates that the process is completed properly and does not indicate that the user passes the verification). •FAILED: The verification process is incomplete or an error has occurred. Note: In "flash" mode, if the user does not pass the "look in the mirror" step in 30 seconds, the status of the token changes to FAILED. •CANCELLED: The user has canceled the verification process. •TIMEOUT: The process has timed out. (If the status is "NOT_STARTED" or "PROCESSING", the liveness_result and verify_result fields are not returned.)	"OK"
fail_reason	String	If "get_fail_reason" is set to 1, the value of this field indicates the reason for the "WEBRTC_UNSUPPORTED" failure. •NETWORK_ERROR: Network connection issue. •PERMISSIONS_ERROR: The user has denied the camera permission or the browser (app) cannot use the camera. •SUPPORT_ERROR: The browser does not support WebRTC APIs or other compatibility issues.	"NETWORK_ERROR"
biz_info	JSON	This field contains `biz_id`, `biz_no`, and `biz_extra_data`. •biz_id: The business ID used to query comparison results. •biz_no: The serial number of the customer business, which is returned in notify and return. •biz_extra_data: The additional data returned when notify_url and return_url are invoked. You can use this to pass additional information.	"biz_extra_data": "...","biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1""biz_no":"cc47190f-5502-44a2-ab74-ea4f0f649f61"
time_used	Int	The time taken by the entire request in milliseconds. This field is always returned.	100
liveness_result	JSON	The result of the liveness detection. If the user cancels the liveness detection process before it is completed, this field is not returned. •result: The result of the liveness detection. Valid values: PASS: The user passes the liveness check. FAIL: The user fails to pass the liveness check. •procedure_type: The method of the liveness detection. Valid values: flash:Flash-based liveness detection. still: Passive liveness detection with a video selfie. •details: The detailed result of the liveness detection. Fields include: If procedure_type is "flash": FACE_NOT_FOUND: The number of times where no face is detected SIDE_FACE:The number of times where the user does not face the screen (tilting to the side). UPDOWN_FACE:The number of times where the user does not face the screen (tilting upward or downward) EYE_OCCLUSION: The number of times where the user's eyes are covered MOUTH_OCCLUSION: The number of times where the user's mouth is covered AWAY_FROM_CAMERA: The number of times where the user is too far away from the camera CLOSE_TO_CAMERA: The number of times where the user is too close to the camera FACE_OUT_OF_CAMERA: The number of times where the user's face is out of view HIGH_BRIGHTNESS: The number of times where the lighting is too bright LOW_BRIGHTNESS: The number of times where the lighting is too dark LOW_FACE_QUALITY:The number of times where the face quality of the video is too low If procedure_type is "still": UPLOAD_TIMES: The number of video uploads FACE_NOT_FOUND: The number of times where no face is detected in the video LOW_FACE_QUALITY: The number of times where the face quality of the video is too low INVALID_VIDEO_DURATION: The number of times where the video duration is invalid SR_ERROR: The number of times where voice recognition results are incorrect (ignore this for passive liveness detection) NOT_SYNCHRONIZED: The number of times where lip reading results are incorrect (ignore this for passive liveness detection) NO_AUDIO: The number of times where the video has no sound VIDEO_FORMAT_UNSUPPORTED: The number of times where the video format is invalid VIDEO_FACE_INCONSISTENT: Face inconsistencies in the video •face_genuineness: This identifies spoof attacks with four sets of confidence scores and thresholds ranging from 0 to 1. If a confidence score is greater than its threshold, a spoof attack in that category is identified. synthetic_face_confidence: The confidence score for synthetic faces synthetic_face_threshold: The threshold for synthetic faces mask_confidence: The confidence score for masks mask_threshold: The threshold for masks screen_replay_confidence: The confidence score for screen replays screen_replay_threshold: The threshold for screen replays	{ "result": "PASS/FAIL", "procedure_type": "still", "details": { "UPLOAD_TIMES": 5, "FACE_NOT_FOUND": 0, "LOW_FACE_QUALITY": 0, "INVALID_VIDEO_DURATION": 1, "SR_ERROR": 2, "NOT_SYNCHRONIZED": 1, "VIDEO_FORMAT_UNSUPPORTED": 0, "NO_AUDIO": 0 }, "face_genuineness": { "synthetic_face_confidence": 0.88, "synthetic_face_threshold": 0.5, "mask_confidence": 0.32, "mask_threshold": 0.5, "screen_replay_confidence": 0, "screen_replay_threshold": 0.5 } }
verify_result	JSON	The result of the face comparison. If the user interrupts the process of liveness check midway or the comparison_type selected by the user is -1, this field will not be returned. •error_message: The error that occurs during face comparison. Valid values: null: No error has occurred.NO_FACE_FOUND: No face detected in the image. Fees are incurred even if this error has occurred. DATA_SOURCE_ERROR: An error has occurred while comparing data. Generally, this indicates a data error. If this error occurs, please stop the service and contact FaceID customer service or business support. Wait until this issue is addressed to start the service again. INTERNAL_ERROR: Internal server error. If this error occurs, send the request again. If this persists, contact FaceID customer service or business support. •result_ref[x]: The comparison result between the face collected in liveness detection and the uploaded image_ref[x]. "confidence": The overall confidence score ranging from 0 to 100 in float. A larger number indicates a lower risk. "thresholds": A set of reference thresholds for the confidence score. The value of this field is an object and contains the following four float fields that range from 0 to 100. "1e-3": The confidence threshold for a risk level of one in a thousand. "1e-4": The confidence threshold for a risk level of one in ten thousand. "1e-5": The confidence threshold for a risk level of one in a hundred thousand. "1e-6": The confidence threshold for a risk level of one in a million. •verify_time: The timestamp of the verification in seconds. This field is returned only if return_verify_time=1.	{ "verify_time": 1462259763, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } } }
images	JSON	The image obtained in the liveness detection. The return_image parameter determines whether this field is returned. The value of this field can be an image in JPG format as a base64 string or null. An image is returned only if the status field is "OK". •image_best: The best-quality image in the liveness detection.	"image_best":"data:image/jpeg; base64,..."
multifaces_tag	String	This field is returned only if the return_multifaces_tag parameter is 1. •0: A single face. •1: Multiple faces.	0
multifaces_image	String	If multifaces_tag is 1, this field is returned with an image that contains multiple faces. The image is a base64 string in JPG format. If multifaces_tag is 0, this field is empty.	"data:image/jpeg;base64,..."

Return value example

Correct request return example

{
    "request_id": "1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c",
    "status": "OK",
    "biz_info": {
        "biz_extra_data": "...",
        "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
        "biz_no": "cc47190f-5502-44a2-ab74-ea4f0f649f61"
    },
    "liveness_result": {
        "procedure_type": "flash",
        "result": "PASS/FAIL/TIMEOUT",
        "details": {
            "UPLOAD_TIMES": 5,
            "FACE_NOT_FOUND": 0,
            "LOW_FACE_QUALITY": 0,
            "INVALID_VIDEO_DURATION": 1,
            "SR_ERROR": 2,
            "NOT_SYNCHRONIZED": 1,
            "VIDEO_FORMAT_UNSUPPORTED": 0,
            "NO_AUDIO": 0
        },
        "face_genuineness": {
            "synthetic_face_confidence": 0.88,
            "synthetic_face_threshold": 0.5,
            "mask_confidence": 0.32,
            "mask_threshold": 0.5,
            "screen_replay_confidence": 0,
            "screen_replay_threshold": 0.5
        }
    },
    "verify_result": {
        "result_ref1": {
            "confidence": 68.918,
            "thresholds": {
                "1e-3": 64,
                "1e-4": 69,
                "1e-5": 74,
                "1e-6": 79.9
            }
        }
    },
    "images": {
        "image_best": "data: image/jpeg;base64,..."
    },
    "time_used": 93
}

Failed request return example

{
    "error_message": "RESULT_NOT_FOUND",
    "request_id": "1462259901,fa79992d-ca61-48de-aa50-ea337c6aad42",
    "time_used": 4
}

Error code list

HTTP status code	error message	illustrate
400	RESULT_NOT_FOUND	This error indicates that the business ID is incorrect.
400	VIDEO_FACE_OCCLUDE	The face in the uploaded video is obstructed.

General ERROR_MESSAGE

HTTP status code	error message	illustrate
403	AUTHENTICATION_ERROR	api_key and api_secret do not match.
403	AUTHORIZATION_ERROR:<reason>	The api_key is disabled, call limit is reached, no permission to call this API, or no permission to call this API with the current method. Valid values for <reason> include "Denied." (no permission to call this API).
403	CONCURRENCY_LIMIT_EXCEEDED	The concurrency limit is exceeded.
400	MISSING_ARGUMENTS:<key>	A required parameter is missing.
400	BAD_ARGUMENTS:<key>	An error occurred while parsing a parameter (for example, a parameter is a number but a non-numeric string is used, or the value is too long).
404	API_NOT_FOUND	The API does not exist.
500	INTERNAL_ERROR	Internal server error. If this error occurs, send the request again. If this persists, contact FaceID customer service or business support.