APP-Verify

Version

3.0.0

Description

Upload all the data of FaceID MegLiveStill SDK, and get the result of liveness detection, face comparing and anti-spoofing attack.

Note：

Only FaceID MegLiveStill SDK Version 3.0 or above is supported.

Request URL

Singapore: POST https://api-sgp.megvii.com/faceid/v3/sdk/verify
Indonesia:  POST https://api-idn.megvii.com/faceid/v3/sdk/verify

Note:

Use HTTPS method in a production environment. Please avoid using HTTP methods as it is an unsecure link which remains security risks. If HTTP methods are used in a production environment, service reliability will not be guaranteed.

Permission

The FaceID Web APIs can only be called when accessing FaceID product first. Please contact our sales for the accessing process.

Parameters

Required/Optional	Parameter	Type	Description
Required/Optional	Parameter	Type	Description
Required	sign	String	The signature of the user calling the API. For the specific signature generation method, please refer to the "App-Authentication" document.
Required	sign_version	String	Signature algorithm version, please pass hmac_sha1.
Required	biz_token	String	The biz_token generated from ”App-GetBizToken“ API.
Required	meglive_data	File	The parameter is required if the liveness_type= meglive or liveness_type=still. It needs to upload datas produced by FaceID MegLiveStill SDK Version 3.0 or above, including datas from liveness detection and face detection process. Please directly pass the API, do not make any adjustment to the data packet. The parameter is optional if the liveness_type =raw_image. The comparison result will be returned.

Return Values

Field	Type	Description
Field	Type	Description
request_id	String	Serial number of API calls.
biz_no	String	Business serial number.
time_used	int	Time that the whole request takes. Unit: millisecond. This field must be returned.
result_code	int	Indicate the status code of the comparison result. You can get the specific result and reason according to result_code and result_message. status code 1000 Series: Comparison finished, verification pass. The result is that two faces are from the same person. status code 2000 Series: Comparison finished, liveness verification pass. The result is that two faces are not from the same person according to at least one of authority data or reference photo. status code 4000 Series: the corresponding result of verification status code 4100 Series: liveness jugement failed status code 4200 Series: SDK liveness photo capture failed Please prepare reservation schemes for other results. We will instantly increase error codes. Note: the return of status code 9000 has priority over other error codes.
result_message	String	Get the specific reason according the string, please refer to comparison table of result_code & result_message
verification	Json	This filed will be returned when verbose=1, result status code=1000, 2000 Series. ref1: the comparison result of liveness photo and image_ref1 "confidence": Float type, value between [ 0,100 ]. Higher confidence indicates higher possibility that two faces belong to same person. "thresholds": For reference. Object type, including three fields of Float type, value between [ 0,100 ]： 1e-3: confidence threshold at the 0.1% error rate 1e-4: confidence threshold at the 0.01% error rate 1e-5: confidence threshold at the 0.001% error rate 1e-6: confidence threshold at the 0.0001% error rate ref2: the comparison result of liveness photo and image_ref2 (only returns when get_biz_token includes image_ref2, the same result as ref1 field）
images	Json	A list of images. The corresponding image field will be added later according to captured images. image_best: liveness image, base64 encoding。
attack_result	Json	The string will only be returned when the status code is not 4200. result: int, 0: real face, 1: fake face score: float, value[0,1], indicates confidence of attack threshold: float, indicates threshold of attack judgement
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 "device_risk=1" 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 is_root: suspected device is rooted is_hook: suspected 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..
video_key	String	Decryption Key, used to retrieve the videos and photos saved on the SDK side.
error	String	This string will not be returned unless request fails , or empty else. For more details, please see the following section on error message.
visual_attributes	Json	“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 Note: This parameter is returned when the get_biztoken interface turns on verification risk detection (verify_risk_detect=1).
verify_risk_info	Json	Comparison risk warning results: "verify_info_tags": Json type; indicates the risk type of liveness image comparison “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: This parameter is returned when the get_biztoken interface turns on verification risk detection (verify_risk_detect=1).

Sample Response

Sample response when request has succeeded:

{
   "time_used":1448,
   "verification":{
      "idcard":{
         "confidence":86.63057,
         "thresholds":{
            "1e-3":51.244865,
            "1e-5":75.758,
            "1e-4":58.77636,
            "1e-6":79.041
         }
      }
   },
   "attack_result":{
      "score":0.26,
      "threshold":0.5,
      "result":False
   },
   "risk_info":{ 
      "device_info_level": "2", 
      "device_info_tags": {"is_root":0,"is_hook":1,"is_injection":1,"is_virtual_environment":1}
   },
   "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
   "images":{
      "image_best":"xxxxxxxxxxx"
   },
   "biz_no":"",
   "result_message":"SUCCESS",
   "result_code":1000
}

Sample response when request has failed:

{
    "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}

Comparison table of result_code & result_message

Result_code	Result_message	Description	Cost
Result_code	Result_message	Description	Cost
1000	SUCCESS	Portrait to be compared and authority data, or reference photo, are from the same person.	Yes
2000	PASS_LIVING_NOT_THE_SAME	Liveness detection passed. As for the verification process, the two faces are not from the same person according to at least one of authority data or reference photo.	Yes
4100	FAIL_LIVING_FACE_ATTACK	Failed to pass liveness verification. Possible reason: fake face attack.	No
4100	VIDEO_LACK_FRAMES	The obtained liveness data fault, please retry with another phone.	No
4100	FAIL_EYES_CLOSE_DETECTION	Failed to pass eye close detection	No
4100	DEVICE_RISK	Device attack detected. Failed to pass liveness detection.	No
4200	BIZ_TOKEN_DENIED	Invalid biz_token	No
4200	AUTHENTICATION_FAIL	Authentication failed	No
4200	MOBILE_PHONE_NOT_SUPPORT	Phone not supported	No
4200	SDK_TOO_OLD	SDK version is too old	No
4200	MOBILE_PHONE_NO_AUTHORITY	No authority (motion sensor, storage, camera)	No
4200	USER_CANCELLATION	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	USER_TIMEOUT	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	VERIFICATION_FAILURE	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	UNDETECTED_FACE	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No
4200	ACTION_ERROR	Liveness verification failed. Possible reasons: user cancellation, verification process timeout, etc.	No

ERROR Message

Status Code	Error Message	Description
Status Code	Error Message	Description
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	The image which <param> indicates can not be resolved. The file format may not be supported or the file is damaged. <param> is one of image_ref1 and image_ref2. Please note that <param> has only one item, that is, the first one that satisfies the condition.
400	MISSING_ARGUMENTS:<key>	Some required arguments missed.
400	BAD_ARGUMENTS:<key>	Error while parsing some arguments. This error may be caused by illegal type or length of argument.
400	NO_FACE_FOUND:<param>	No face is detected in image_ref.
400	INVALID_IMAGE_SIZE:<param>	The size of uploaded image is too large, which is over the 4096x4096 pixel limit. <param> is one of image_ref1 and image_ref2. Please note that <param> has only one item, that is, the first one that satisfies the condition.
400	MEGLIVE_DATA_ERROR	Failed to parse meglive_data packet. Please pass the original data packet directly to the API. Any adjustment to the data packet will cause problems.
400	MEGLIVE_DATA_BIZ_TOKEN_NOT_MATCH	The biz_token of meglive_data is not consistent with biz_token imported.
403	AUTHORIZATION_ERROR:<reason>	api_key is discontinued, rate limit has been exceeded, no permission to call the API, or no permission to call the API according to current method. Values of <reason> are: API_KEY_BE_DISCONTINUED：api_key is discontinued IP_NOT_ALLOWED：IP is not allowed LIMIT_REACHED：the limit of API calls for the api_key(only for test api_key) has been exceeded MORE_RETRY_TIMES：comparison retry limit is reached NO_VERIFY_PERMISSION：no permission for non-data-source comparison, but still calls NO_DATA_SOURCE_PERMISSION：no permission for data-source comparison, but still calls DENIED：no permission to call the API EXPIRED_SIGN：signature is expired INVALID_SIGN：invalid signature Please prepare reservation schemes for other results
429	CONCURRENCY_LIMIT_EXCEEDED	The rate limit for this API Key has been exceeded.
404	API_NOT_FOUND	Requested API can not be found.
413	Request Entity Too Large	The request entity has exceeded the limit (20MB) or single photo size exceeds 2MB. This error message will be returned in plain text, instead of JSON.
500	INTERNAL_ERROR	Internal error. Please retry the request. If this error keeps occurring, please contact our support team.