APP_Pro-Liveness

Version

5.0.0

Description

This interface is used to upload data obtained from FaceID SDK and obtain result information such as liveness check.

URL

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

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

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			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.
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.
		Optional	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_type=1	Conditionally mandatory	image	File	Pass the self-owned photo for verification.
		Conditionally 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.
		Conditionally 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.

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 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.
#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. 注： 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：Indicate no risk；1：Indicate medium risk (recommended for business verification) ；2：Indicate high risk (directly intercepted by Face ID) "device_info_tags"：Json type; indicating the type of device risk Device risk Tag Remarks is_root Suspect that the device is rooted is_hook Suspect that the device is hooked is_injection Suspect that the device is injected is_virtual_environment Suspect that the device is running in a virtual environment N ote："device_info_tags"will expand with the development of the business.
#Face attack information description	face_risk_info	Json	Face Risk Detection Results: "face_info_tags"：Json type；ndicating 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 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.
	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":{
      "idcard":{
         "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
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.