APP_Pro-Verify

Version

5.0.0

Description

This interface is used to upload data obtained from FaceID SDK and obtain result information such as liveness verification, face comparison and attack prevention.

URL

Singapore:https://api-sgp.megvii.com/faceid/v5/sdk/verify

Indonesia region:https://api-idn.megvii.com/faceid/v5/sdk/verify

Request mode

POST

Parameters

Optional/mandatory			Parameter name	Parameter type	Parameter description
Mandatory			sign	String	Customer's signature for invoking this API. Please refer to the "Authentication Guide" document for the specific method of generating the signature.
Mandatory			sign_version	String	Please pass the signature algorithm version number as "hmac_sha1"
Optional			biz_no	String	Customer's business serial number, recommended to be set as a unique serial string related to your business. It will be returned to your server as is during the 'return' process, helping you confirm the ownership of the corresponding business. This field should not exceed 128 bytes.
Mandatory			comparison_type	String	Please pass 0 as the verification method for this request.
Mandatory			data_type	String	Data source for verification: 0： Identity verification and validation through SDK 5.0.0 or above 1：Identity verification and validation using self-uploaded photos.
Mandatory			verify_id	String	Verification scene ID: The relevant configuration for this verification request can be set in the console, and the generated ID number should be used in the interface.
Mandatory			encryption_type	String	Whether to enable data encryption during transmission: 0: Not open 2: RSA For detailed information, please refer to the "Encryption Guide" document.
Data to be verified is passed in	data_type=0	Conditionally mandatory	biz_token	String	The "biz_token" obtained from the "get_biz_token" interface is used to identify the data object for this verification session.
	data_type=1	Conditionally mandatory	image	File	Pass the self-owned photo for verification.
Reference data input	comparison_type=0	Mandatory	uuid	String	Upload this field to indicate the unique ID of the user corresponding to this recognition session. It should not exceed 128 bytes. It is recommended that you use the same ID for comparison requests from the same user. This is highly beneficial for result verification and obtaining a better data reporting experience.
		Mandatory	image_ref1	File	The reference face photo provided by the application. If no face is found in either image_ref1 or image_ref2, an error code 400 (NO_FACE_FOUND) will be returned. If there are multiple faces in any of these images, the largest face will be selected for comparison.
		Optional	image_ref2	File	The reference face photos provided by the application. If no face is found in either image_ref1 or image_ref2, an error code 400 (NO_FACE_FOUND) will be returned. If there are multiple faces in any of these images, the largest face will be selected for comparison.

Returned results

Parameter category	Parameters	Type	Remarks
#Basic return information	request_id	String	Unique character string used to distinguish each request.
	biz_no	String	The business serial number passed in will be returned as is.
	time_used	Int	Time spent for the whole request (unit: millisecond). This field must be returned.
	user_faced_time	String	The time when the user's face was detected.
	error	String	This character string will be returned only in case of failed request. Detailed return is included in the following error section. Otherwise, this field does not exist.
#code	result_code	Int	Indicate the status code of the result of this verification. Specific results and reasons can be obtained by combining with the fields "result_code" and "result_message": The 1000 series status code indicates that the liveness has passed the verification and is the same person The 2000 series status code indicates that the comparison has been completed and the liveness has passed the verification, but at least one of the images to be compared with the reference image or one of the reference images is not the same person The 4100 series status code indicates that the cloud-based liveness has not passed the detection The 4200 series status code indicates SDK liveness image acquisition has failed For other results, please reserve a processing scheme. For possible errors in the future, we may continue to increase the error code Note: The return priority of the 9000 series is higher than other error codes.
#Status code description	result_message	String	The specific reason can be known through this field information. For details, please refer to the comparison table of result_code & result_message.
#Comparison results	verification	Json	"ref1"： comparison results between the liveness image collected and image_ref1 uploaded "confidence"：Float type, with a value of [0,100]. A larger number indicates a lower risk. “thresholds”：a set of confidence thresholds for reference; Object type; consisting of three fields (all of Float type), with a value of [0,100]: “1e-3”：confidence threshold with a risk of 1/1000 confidence threshold with a risk of 1/10000 confidence threshold with a risk of 1/100000 confidence threshold with a risk of 1/1000000 ref2：comparison results between the liveness image collected and image_ref2 uploaded (only returned if image_ref2 exists in the 'verify', and the result ref1 field is returned)
#Attack results	attack_result	Json	"result"：Bool type,with values ofTrueorFalse。Represent the result of cloud attack judgment, with 'False' indicating not an attack and 'True' indicating an attack. "score"：Float type, with a value of[0,1].Represent the score of an attack, with a higher score indicating a higher likelihood of an attack. "threshold"：Float type,with a value of[0,1]. Represent the threshold of an attack. 注： When the parameter is set as "force_compare=1", the API will ignore the liveness judgment on the cloud, and users need to use this field to determine whether it is a liveness. The default strategy adopted by the cloud is that it may be an attack when score>=threshold.
#Device attack information description	device_risk_info	Json	Device risk detection results: "device_info_level": string type, 0: indicates no risk detected; 1: indicates medium risk (business verification is recommended); 2: indicates high risk(Face ID is directly blocked. If turns on device risk detection and performs high-risk blocking, such risk requests will be blocked) "device_info_tags"：Json type; indicating the type of device risk Device risk Tag Remarks is_root suspected device is rooted is_hook Suspect that the device is hooked is_injection suspected device is injected is_virtual_environment suspected device is running in a virtual environment is_double_open suspected device is double-open (only Android device detection) is_group_control_risk suspected group control device risk (only Android device detection) is_non_system_user suspected non-system user (only Android device detection) is_location_spoofed suspected fake location (only Android device detection) is_using_vpn suspected VPN software is used is_using_agent suspected agent software is used (only IOS device detection) is_usb_inserted suspected device is in USB plugged in state (only Android device detection) is_screen_casting suspected device is in screen casting state (only IOS device detection) is_anomalous_behavior suspected device has abnormal behavior in recent identification is_other_risks other device risks Note："device_info_tags"will be added, modified, deleted, and expanded as the business develops. It is recommended to upgrade to the latest version of the SDK to detect more device risk tags.
#Face attack information description	face_risk_info	Json	Face risk detection results: "face_info_tags"：Json type；indicates the types of face attack risks； face risk tag Explanation is_photo Photos is_screen_remake Screen Replay is_paper_cut Cutouts, Stickers is_paper_mask Paper Masks is_3d_mask 3D Masks is_facial_mask Face Masks, Respirators is_software_composition AI Synthesis is_eye_close Closed Eyes is_change_face Face Swap in Action is_high_risk_background High-risk background others Others
#Additional return information	images	Json	A list of images: corresponding image fields will be added based on the collected images in the future. image_best: a photo of liveness (base64 coding).
	video_key	String	Decryption key: used to obtain videos and images saved on the SDK (not a mandatory return field, with permission required).
	visual_attributes	Json	Additional Attributes: “age”: estimated age of the person being verified “gender”: estimated gender of the person being verified “age_image_ref1”: estimated age of reference face image ref1 “gender_image_ref1”: estimated gender of reference face image ref1
	verify_risk_info	Json	Comparison risk warning results: "verify_info_tags"：Json type；indicates the risk type of liveness image comparison Comparison risk tag Explanation is_gender_risk string type, 0: indicates that the gender of the liveness image and the comparison image is consistent; 1: indicates that the gender of the liveness image and the comparison image is inconsistent; (gender comparison between the liveness image and the ref1 image) is_age_risk string type, 0: indicates that the age difference between the liveness image and the comparison image is not significant; 1: indicates that the age difference between the liveness image and the comparison image is significant (usually referring to an age gap of 10 years or more, depending on the threshold setting. The age comparison is between the liveness image and the ref1 image) Note：The parameter is returned only when "verify risk detection" is turned on in the console Verify scenario.
	face	Json	When using the "rawimage" method, the attributes of the verification image are returned, including: "quality"：Face quality. "quality_threshold"：Face quality threshold. "rect"：Face coordinate points in JSON format. "orientation"：Face orientation.

Example of return value

Example of correct request for return

{
   "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
   "biz_no":"",
   "time_used":1448,
   "user_faced_time":"1699422077",
   "result_code":1000,
   "result_message":"SUCCESS",
   "verification":{
      "ref1":{
         "confidence":86.63057,
         "thresholds":{
            "1e-3":62.168713,
            "1e-5":74.39926,
            "1e-4":69.31534,
            "1e-6":78.038055
         }
      }
   },
   "attack_result":{
      "score":0.26,
      "threshold":0.5,
      "result":False
   },
   "device_risk_info":{
      "device_info_level": "2",
      "device_info_tags": {"is_root":0,"is_hook":1,"is_injection":1,"is_virtual_environment":1}
   },
   "face_risk_info":{
      "face_info_tags":{"is_photo":0,"is_screen_remake":1,"is_paper_cut":0,"is_paper_mask":0,"is_3d_mask":0,"is_facial_mask":0,"is_software_composition":0,"is_eye_close":0,"is_change_face":0,"other":0}
   },
   "images":{
      "image_best":"xxxxxxxxxxx"
   },
   "video_key":"asdffff",
   "visual_attributes":{
      "age":16,
      "gender":0
   },
   "face":{
      "quality":38.221,
      "quality_threshold":30.1,
      "rect":{
         "left":0.18,
         "top":0.18,
         "width":0.596,
         "height":0.596
       },
      "orientation":90
   }
}

Example of wrong request

{
    "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}

Comparison table of result_code & result_message

result_code	result_message	Explanation of meaning	Whether to charge
1000	SUCCESS	The person in the image to be compared is the same person as in the other images.	yes
2000	PASS_LIVING_NOT_THE_SAME	Passed the liveness detection, but the person in the image to be compared was not the same person as in at least one of the other images after verification.	yes
4100	FAIL_LIVING_FACE_ATTACK	Failed to pass the liveness detection (possible cause: fake face attack).	yes
4100	VIDEO_LACK_FRAMES	The obtained liveness data is faulty. Please try again with a different mobile phone.	no
4200	BIZ_TOKEN_DENIED	The provided biz_token does not meet the requirements.	no
4200	AUTHENTICATION_FAIL	Authentication failed	no
4200	MOBILE_PHONE_NOT_SUPPORT	The mobile phone is not contained in the support list	no
4200	SDK_TOO_OLD	The SDK version is too old to be supported.	no
4200	MOBILE_PHONE_NO_AUTHORITY	No authorities (motion sensors, memories and cameras).	no
4200	USER_CANCELLATION	The user failed to pass liveness detection, possibly due to reasons such as user cancellation, verification process timeout, etc.	no
4200	USER_TIMEOUT	The user failed to pass liveness detection, possibly due to reasons such as user cancellation, verification process timeout, etc.	no
4200	VERIFICATION_FAILURE	The user failed to pass liveness detection, possibly due to reasons such as user cancellation, verification process timeout, etc.	no
4200	UNDETECTED_FACE	The user failed to pass liveness detection, possibly due to reasons such as user cancellation, verification process timeout, etc.	no
4200	ACTION_ERROR	The user failed to pass liveness detection, possibly due to reasons such as user cancellation, verification process timeout, etc.	no
4200	GET_CONFIG_FAIL	The user failed to pass liveness detection due to failure to get configuration.	no

Error message

HTTP status code	Error message	Remarks
400	MISSING_ARGUMENTS:<key>	One mandatory parameter is missing.
400	BAD_ARGUMENTS:<key>	One parameter is wrong in parsing (e.g., a non-numeric character string is input for a parameter that allows only numeric values; or such parameter is too long.) note：<meglive_data>The error means that the current token does not call the SDK, and an error is reported due to lack of living data.
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	Corresponding image of <param> cannot be analyzed, It may not be an image file or relevant data is damaged. <param>may be image_ref1, image_ref2 or image. Attention: There will only be one item for <param>, which is the first name that meets the condition.
400	NO_FACE_FOUND:<param>	Indicate that no face was found in the uploaded images of "image_ref" and "image".
400	INVALID_IMAGE_SIZE:<param>	The uploaded image is too large, that is, the length or width of the pixel size exceeds 4096 pixels. <param> may be image_ref1, image_ref2 or image. Attention: There will only be one item for <param>, which is the first name that meets the condition.
400	LOW_QUALITY	The image quality is too low.
400	MULTIPLE_FACES	There are multiple faces in the image.
400	MEGLIVE_DATA_ERROR	Failed to parse the uploaded "meglive_data" data packet. Please pass the "meglive_data" data packet generated by the SDK directly to this API. Any modifications to the data packet will cause the packet parsing failure.
400	DATA_APPKEY_NOT_MATCH	The key/token in the uploaded MegLive data package does not match the corresponding key.
400	FMP_CONTENT_TYPE_ERROR	There was an error with the video. Please try again or try using a different phone.
400	KEY_NOT_FOUND	encryption_type is enabled for encryption, but encryption public key and decryption private key are not configured.
403	AUTHENTICATION_ERROR	Invalid signature.
403	AUTHORIZATION_ERROR:<reason>	The API key has been deactivated, the call limit has been exceeded, there is no permission to access this API, or there is no permission to access this API in the current manner. Possible values for <reason>: API_KEY_BE_DISCONTINUED：The API key has been deactivated. IP_NOT_ALLOWED：The accessing IP is not allowed (reserved design). LIMIT_REACHED：The call limit for this API with the given API key has been reached. Only applicable for test keys. MORE_RETRY_TIMES：The maximum retry attempts for comparison have been reached. NO_VERIFY_PERMISSION：There is no permission for face verification, but the request attempted to call it. NO_DATA_SOURCE_PERMISSION：There is no permission for KYC verification, but the request attempted to call it. NO_EID_PERMISSION：There is no permission for identity verification, but the request attempted to call it. DENIED：There is no permission to call the current API. EXPIRED_SIGN：The signature has expired. INVALID_SIGN：The signature is invalid. NO_LIVENESS_PERMISSION：There is no permission for liveness detection, but the request attempted to call it. Please prepare handling solutions for other possible error codes as well.
403	CONCURRENCY_LIMIT_EXCEEDED	The concurrent number of requests has exceeded the limit.
404	API_NOT_FOUND	The API called does not exist.
413	Request Entity Too Large	The request sent by the customer exceeds the 20MB MB limit, or the size of a single image exceeds 2MB. The return for this error will be plain text, not in "json" format.
500	INTERNAL_ERROR	Internal server error. Please retry your request when such errors occur. If you continue to experience this issue, please contact FaceID customer support or your business representative for assistance.