App-GetBizToken

Version

1.0.0

Description

Configure the identity verification function of Face Comparing, support non-data-source comparison (compare portrait to be verified and reference portrait without sources). You can pass the liveness detection configuration to FaceID server for the initialization of the FaceID MegLiveStill SDK. The biz_token will be returned after verification is valid.

Note：

Only FaceID MegLiveStill SDK Version 3.0 or above can access biz_token for initialization.

Under FaceID MegLiveStill SDK Version 3.0, please refer to the document “Verify 2.0.6” under “Face Verification API”.

Request URL

POST https://api-sgp.megvii.com/faceid/v3/sdk/get_biz_token

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		sign	String	The signature when calling the API. For specific signature generation method, please refer to "App-Authentication" documentation.
Required		sign_version	String	Signature algorithm version. Please pass hmac_sha1.
Required		liveness_type	String	Choice of liveness detection process, see values below: meglive: motion-based liveness detection still: still liveness detection raw_image: no liveness detection, the image uploaded will be used in the following comparison
Required		comparison_type	String	Define the comparison type. The value can only be 0, otherwise it will cause error 400(BAD_ARGUMENTS ). “0” presents non-data-source comparison. The photo provided by the user will be taken as a reference portrait.
Required		uuid	String	Upload this field if not to use data sources for face comparing. The field, which should not be longer than 128 bytes, marks the user corresponding to the detection with a unique ID. It is recommended to use the same ID for the same user's requests, since it is very convenient to check the verification results and acquire a better experience in monitoring report.
Required		image_ref1	File	Reference portrait provided by client. If no face is detected in any of image_ref1, image_ref2, Error 400 (NO_FACE_FOUND) will be returned. If multiple faces are found in the two images, the biggest face will be chosen for comparison.
Optional		image_ref2	File	Reference portrait provided by client. If no face is detected in any of image_ref1, image_ref2, Error 400 (NO_FACE_FOUND) will be returned. If multiple faces are found in the two images, the biggest face will be chosen for comparison.
Optional		biz_no	String	Business serial number. The default value is empty. It is recommended to be set related to your business and uniquely. It will be returned to your server when execute “return” value, which helps you confirm the attribution of the corresponding business. This field does not exceed 128 bytes.
Optional		liveness_timeout	String	The timeout after one enters the liveness detection process. The verification will be failed if it is not completed within the set time. Timeout setting: unit seconds, ∈ [5, 60] meglive: set the timeout for each action, the default is 10. still: set the timeout for the mirror, the default is 60.
liveness_type = meglive	Optional	liveness_action_count	String	The number of actions when configuring Motion-based liveness detection. The default is 3 actions; the default is 3, ∈ [1,3]
liveness_type = still	Optional	eyes_close_detection	String	Wether execute eye close detection in still liveness detection. The value is 1 or 0: “0”: default value, no eye blinking detection “1”: eye blinking detection mode. *The liveness detection will be failed if one keeps eyes-closed states.
liveness_type = raw_image	Required	image	File	Portrait to be compared. This method will detect all the faces in the image, and evaluate the quality of the biggest face. You can set the optional parameters "fail_when_multiple_faces" and "face_quality_threshold" to define the detection standard.
	Optional	fail_when_multiple_faces	String	Whether returns error or continues comparing when multiple faces are detected. The value is 1 or 0: 1: error 400 (MULTIPLE_FACES) returned 0: continues comparing with the biggest face detected
	Optional	face_quality_threshold	String	The quality threshold of the biggest face within the image. The default value is 30. When the quality of a detected face is lower than the threshold, error 400 (LOW_QUALITY) will be returned. Only an integer parameter between 0 to 100 is allowed, or error 400 (BAD_ARGUMENTS) will be returned.
	Optional	return_faces	String	Returns the detection result. The value can only be 1 or 0. 1: returns the detection result 0: only returns the comparison result other values: error 400 (BAD_ARGUMENTS) occurs Attention: When the set value is 1, even if error 400 (LOW_QUALITY), 400 (MULTIPLE_FACES), 400 (NO_FACE_FOUND) returned, the result still contains "faces" string.
Optional		verbose	String	The extent of detail of the returned data. The values are below: 0: default value, only returns conclusion 1: returns conclusion and summary
Optional		security_level	String	The strictness of the comparison result. Please select the security rule based on your scenario. The higher the stricture is, the higher the accuracy requires, and the lower the pass rate becomes. 1: loose 2: regular (default) 3: strict 4: very strict
Optional		force_compare	String	Whether comparison is still performed after a fake face is determined. 0: Default value, no comparison. When a fake face is determined, the result will be directly returned without performing comparison, which can save your costs. 1: Perform comparison. After a fake face is determined, comparison is still performed. It will not return fake face result, but the comparison result. The risk situation can be checked by verification (need to set verbose=1). Attention: The record will be included in the billing logic when comparison is turned on.
Optional		multi_oriented_detection	String	Decide wether the image corresponding to the image_ref[x] parameter needs rotation (90 degrees, 180 degrees, 270 degrees) for a re-detection when no face detected. The value can only be 1 or 0: 1: default value, rotation 0: no rotation Other values: Error 400 (BAD_ARGUMENTS) occurs Attention: Set this parameter to 1 may slightly increase the probability of misdetection. It is recommended not to set this parameter if you are clear that there does not exist non-axial face image or an extremely low-probability in your business.

Return Values

Field	Type	Description
Field	Type	Description
request_id	String	Unique ID of each request. This string can be used for subsequent data check. This field must be returned.
time_used	Int	Time that the whole request takes. Unit: millisecond. This field must be returned.
biz_token	String	Information passed when the SDK is called. Note: biz_token is unique and can only be used once. One biz_token is valid for 1 hour.
error	String	This string will not be returned unless request fails. For more details, please see the error message.

Sample Response

Sample response when request has succeeded:

{
   "biz_token":"1531397038,f0b9eea0-6a2d-486c-a1ba-42fdf843e8cc",
   "time_used":18,
   "request_id":"1531397037,c1223c5b-c2f6-4bb7-8cbb-8993497ddbe0"
}

Sample response when request has failed:

{
    "error": "BAD_ARGUMENTS: sign_version"
}

ERROR Message

Status Code	Error Message	Description
Status Code	Error Message	Description
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	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	NO_FACE_FOUND:<param>	No face is detected in any of image_ref1, image_ref2. <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	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, image_ref2.Please note that <param> has only one item, that is, the first one that satisfies the condition.
400	LOW_QUALITY	The image quality is low.
400	MULTIPLE_FACES	The image contains multiple faces.
403	AUTHENTICATION_ERROR	Invalid signature.
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 below: 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：sign is expired INVALID_SIGN：invalid sign Please prepare reservation schemes for other results
403	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 (5MB). 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.