Describe

This API is used to verify the liveness detection results, compare faces, and identify attacks after the Raw-ValidateStill API is called.

You can call this API if the apikey has video verification or selfie verification permissions of the webpage face verification API service. Otherwise, the API returns the error code 403 (AUTHORIZATION_ERROR:Denied).

Call URL

Singapore region ：https://api-sgp.megvii.com/faceid/lite/raw/verify

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

POST Note: Use form-data format to request

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	token	String	Use the token_still returned by the Raw-ValidateStill API.
Optional	biz_no	String	The string used to identify a verification process. The maximum length is 128 characters. If you want to use this parameter, we recommend that you use the same biz_no for the API calls (such as Raw-ValidateStill and Raw-Verify) in the same verification process and use different biz_no for different verification processes.
Required	comparison_type	String	The valid values of this parameter are listed below. If you use other values, the error code 400 (BAD_ARGUMENTS) is returned. •"0" specifies face comparison, which compares the face image with the photos you provide (image_ref[x]). Note: If the appkey does not have face comparison permissions, setting this value will return the error code 403 (AUTHORIZATION_ERROR:Denied)
Required	uuid	String	If no reference data is used for comparison, this field is uploaded. This parameter is the ID used to uniquely identify the user in this verification. The length of this parameter cannot exceed 512 bytes. We recommend that you use the same ID for comparison requests of the same user to help you query and view verification results and obtain better reports.
Required	image_ref[x]	File	The face reference photos you provide. x indicates that you can provide multiple photos. In this case, 1 <= x <= 3 and 3 face reference photos can be uploaded (the parameters are image_ref1, image_ref2, and image_ref3). If no face is detected in one of the photos in image_ref[x], the error code 400 (NO_FACE_FOUND) is returned. If multiple faces are detected in one of the photos, the error code 400 (MULTIPLE_FACES) is returned.
Optional	multi_oriented_detection	String	This parameter specifies whether to rotate the photos in image_ref[x ] by 90, 180, and 270 degrees for face detection if no face is detected. The valid values of this parameter are "1" and "0" (default is "0"). • "1": Rotate. •"0": Do not rotate. • Other value: The error code 400 (BAD_ARGUMENTS) is returned. Note: Setting this parameter to 1 might increase the false positive rate of face detection. If your business scenario does not contain or contain few photos with different orientations, you can ignore this parameter.
Optional	fail_when_ref_multiple_faces	String	This parameter specifies whether to immediately return an error code if multiple faces are detected in the face reference photos (image_ref[x]). Valid values: •"1": Immediately return error code 400 (MULTIPLE_FACES:). •"0": Use the largest face in the photo for comparison. Note: The default value of this parameter is "1".

Return value description

Field	type	illustrate
request_id	String	The unique string to identify each request. This string can be used to query data later. This field is always returned.
time_used	Int	The time taken by the entire request in milliseconds. This field is always returned.
biz_no	String	This is returned only if the biz_no parameter is specified when you call this API, regardless of whether the request fails. The value is the same as the one you specify.
liveness	Object	This field contains the process verification results and liveness detection results in the two following fields. • procedure_validation: The process verification results. Valid values: "PASSED": The user passes the process verification. "VIDEO_SR_ERROR": The voice recognition results do not meet the requirements (for video verification only). "VIDEO_NOT_SYNCHRONIZED": The lip reading results are incorrect. (for video verification only). "VIDEO_FACE_INCONSISTENT": Inconsistent faces in the video. "SELFIE_INCONSISTENT": The front-facing selfie is inconsistent with the side selfie (for double-angle liveness detection only). "SELFIE_METADATA_INCONSISTENT": The front-facing selfie or side selfie is not in JPG format, or their metadata does not match (only for double-angle liveness detection while liveness_preferences is not "selfie_no_metadata_check"; this is checked before "SELFIE_INCONSISTENT"). •face_genuineness: The results of face spoofing identification. Valid values: "PASSED": The face is not a spoof. "MASK": Mask attack. "SCREEN_REPLAY": Screen replay. "FACEGEN": Software-generated face. Note: •Generally,a user passes if both procedure_validation and face_genuineness are "PASSED". •If procedure_validation is not PASSED, the face_genuineness field is not returned and face comparison is not performed. •Future product updates may add new valid values to the fields or remove existing values from the fields. Please take this into account and make sure your integration is flexible.
result_ref[x]	Object	This field is returned only if image_ref1, image_ref2, or image_ref3 is specified and the API call is successful. The comparison results between image_ref[x ] and the face to be verified are returned in fields result_ref1, result_ref2, and result_ref3. Each of the above fields contains an overall confidence score. •"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. Note: The thresholds are not constant and may change for different comparison operations. You do not need to save the thresholds nor compare a confidence score with a threshold returned from a previous call. For the selection of thresholds, see the following description (for reference only). •You can select the threshold based on the security and user experience requirements of your business. A higher threshold means a higher security level and a lower pass rate. Users may need to verify several times to pass the verification, which affects user experience. A lower threshold can improve the first-time pass rate and user experience at the cost of security due to an increased false positive rate. Please select an appropriate threshold based on your business needs. • The "1e-3" threshold is the lowest threshold. If confidence is lower than the "1e-3" threshold, it is usually considered that the face belongs to a different person. If confidence is slightly higher than the "1e-3" threshold, it is barely enough to consider that the faces belong to the same person. This threshold is suitable for scenarios with fewer security requirements (for example, a separate password must be entered to use certain app features in addition to the face ID login) or strong security requirements but trivial incident consequences (for example, the money transfer scenarios require a high security level, but the transfer amount is small). • The "1e-5" and "1e-6" thresholds are higher thresholds. If the confidence score is higher than the "1e-5" threshold, it is clear that the faces belong to the same person. We recommend that you use the "1e-5" threshold for critical scenarios that require a high level of security, such as large loans or transfers. The "1e-6" threshold is the highest threshold and is suitable for scenarios with the highest level of security requirements. • The "1e-4" threshold lies between "1e-3" and "1e-5". •If you have questions on threshold selection, please contact the FaceID business support or technical support team.
multifaces_tag	String	This field is returned only if the return_multifaces_tag parameter is 1. •0: A single face. •1: Multiple faces.
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.
error_message	String	This string is returned if the request fails. For the details of this field, see the "Error codes" section below. If the request is successful, this field is not returned.

Return value example

Correct request return example

{
    "time_used": 1943,
    "id_exceptions": {
        "id_photo_monochrome": 0,
        "id_attacked": 0
    },
    "liveness": {
        "procedure_validation": "PASSED",
        "face_genuineness": "PASSED"
    },
    "result_ref1": {
        "confidence": 59.873,
        "thresholds": {
            "1e-3": 65.3,
            "1e-5": 76.5,
            "1e-4": 71.8,
            "1e-6": 79.9
        }
    },
    "request_id": "1490012180,eca42fde-ef75-4fb3-8a98-6299e5bf8c4b"
}

Failed request return example

{
    "time_used": 2,
    "biz_no": "3149525e-2c24-4862-8e9f-92040595f0a4",
    "error_message": "INVALID_TOKEN",
    "request_id": "1490026804,adcb6619-c8f0-49ae-a643-00dc77356184"
}

Error code list

HTTP status code	error message	illustrate
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	The <param> parameter is the image that cannot be parsed. The file might not be an image or the data is corrupted. <param> is image_ref1, image_ref2, or image_ref3.
400	NO_FACE_FOUND:<param>	<param> is the image with no face detected.
400	INVALID_TOKEN	The token does not exist, has expired, is invalid, or is not returned by the API with the same API key.
400	INVALID_IMAGE_SIZE:<param>	The image uploaded is too large. The length or width of the image exceeds 4096 pixels. is the name of the parameter that contains the image. Note: If the image size is larger than 2 MB, the error 413 (Request Entity Too Large) is returned.
400	MULTIPLE_FACES:<param>	<param> is the image with multiple faces detected.

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 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, the value is too long, or the value is invalid).
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.