Describe

This API is provided for the FaceID H5 verification service. You can use this API to obtain a token (each token is unique and can only be used once). This API also helps complete face comparison and return the comparison results after verification for easy integration.

Call URL

Indonesia region ：https://api-idn.megvii.com/faceid/lite/get_token

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	return_url	String	The destination URL to redirect to after the user completes or cancels the verification (the callback method is POST).
Required	notify_url	String	The customer server URL the FaceID server requests after the user completes or cancels the verification or the verification times out. (An HTTPS URL is recommended. If an HTTP URL is used, you need to verify the request with a signature. The callback method is POST.) Note: For security reasons, the FaceID verification service only supports ports 443, 5000, 16003, 8883, and 8028 for server callbacks.
Required	biz_no	String	The serial number of the customer business. The value of this parameter must be unique. This number is returned to your server in notify and return to help you confirm business relationships. The length of the value cannot exceed 128 bytes.
Optional	biz_extra_data	String	The additional data returned when notify_url and return_url are invoked. You can use this to pass additional information for debugging and other purposes. The length of the value cannot exceed 4096 bytes.
Optional	scene_id	String	The scene_id of the scene configured in the console. This is used to customize UI elements in the verification process. If you do not pass this parameter, the default scene in the console is used. If no scene is configured in the console, the default solution of the system is used. If you use a scene_id that does not exist, the API fails and returns the error code 400 (BAD_ARGUMENTS).
Optional	language	String	This parameter is optional. This parameter is used to change the language of the page. 0: English (default) 1: Chinese 2: Indonesian 3: Thai 4: Filipino 5: Vietnamesei 6: Spanish
Optional	procedure_type	String	The method of the liveness detection process. Valid values: "flash": Flash-based liveness detection. "distance": 3D liveness detection. "still": Passive liveness detection with a video selfie ranging from 0.5 to 10 seconds. The default value of this parameter is "flash".
Optional	procedure_priority	String	This parameter is optional. This parameter is used to configure the alternative solution when WebRTC is not supported. still: Use still (passive) detection first. If passive detection is not supported, use the pre-installed camera app to record the video. keep: No alternative solution is used. If the browser is not supported, return. Default value: If procedure_type is flash, the default value is "still". If procedure_type is distance, the default value is "still". If you set this parameter to another value, the error code 400 (BAD_ARGUMENTS) is returned.
Optional	get_shooting_error	String	This parameter specified whether to obtain the shooting error. Valid values: "1": Obtain the error for not uploading the video in a long time. "0": Do not obtain the error for not uploading the video in a long time. Note: If the value of this parameter is "1" and the user's video is not received in the FaceID face verification process, the error message {"shooting_error":true/false} is returned in return_url and notify_url. If the value of this parameter is "0", no error message is returned even if the user's video is not received in the FaceID face verification process. The default value is "0".
Optional	maximum_shooting_time	Int	The timeout configuration after the user taps to start shooting. After this time, the pop-up window that contains the message "Recorded video not received in a long time" appears. Note: Valid values of this parameter range from 2 to 60 seconds. The default value of this parameter is 15 seconds. We recommend that you set this to 10 to 15 seconds.
Required	comparison_type	String	Set the type of the service. The current supported options are "liveness check+face comparison" (value "0") and "only liveness check without face comparison" (value "-1"). Passing other values will be recognized and error code 400 (BAD_ARGUMENTS) will be returned. “0” indicates that liveness check+face comparison. “-1” indicates that only liveness check will be operated without face comparison.
comparison_type=0，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.
comparison_type=0，Required	image_ref [x]	File	The face reference photos you provide. x indicates that you can provide multiple photos. In this case, 1 <= x <= 2 and 2 face reference photos can be uploaded (the parameters are image_ref1 and image_ref2). If no face is detected in one of the photos in image_ref1 and image_ref2, 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.
comparison_type=-1，Required	uuid	String	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.
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".
Optional	return_multifaces_tag	String	This parameter specifies whether to return the multiple faces tag. 0: Do not return (default) 1: Return
Optional	fmp_mode	String	This parameter specifies whether to perform cloud face spoofing attack identification in the liveness detection results. The default value is 1. Valid values: 1: Do not perform cloud face spoofing attack identification (synthetic faces, masks, and screen replays) in the liveness detection results, but return the attack scores. You can design subsequent processes based on your business needs and the attack scores. 0: Perform cloud face spoofing attack identification in the liveness detection results. If you choose the RTC liveness detection method (update_rtc), this parameter is ignored and cloud face spoofing attack identification is always performed. Note: For details about the liveness detection results, see the "liveness_result" parameter in the "Return value" section of "Lite-GetResult".
Optional	get_fail_reason	String	This parameter specifies whether to return the reason for failure if the fail_reason is WEBRTC_UNSUPPORTED (default value is "0"). Valid values: 1: Return reason for failure. 0: Do not return reason for failure.
Optional	face_occlusion_detection	String	This parameter specifies whether to enable face occlusion detection. Valid values: 0: Disable (default). 1: Enable. If the user's face is obstructed during the entire process,the verification fails.
Optional	eye_close_detection	String	This parameter specifies whether to enable closed eye detection. Valid values: 0: Disable . 1: Enable(default).
Optional	action_http_method	String	The method used to redirect to return_url. POST: (Default) Return detailed data in the form format. For details, see Callbacks. GET: Return biz_id as a parameter in the return_url. For details, see Callbacks.
Optional	redirect_type	String	The redirect method of the page (if redirect_type =1 and action_http_method=GET, users can go back to the previous page before FaceID Lite by tapping the Back button in the browser or on the phone). Valid values: 0: (Default) Normal redirect if this parameter is not used or 0 is set. 1: Use replace for page redirects, which does not leave a record in the browser's history.

Return value description

Field	type	illustrate
request_id	String	The unique string used 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.
token	String	The string that is used as a parameter to call the DoVerification API to perform liveness detection based on the above configurations. (Note: Each token can only be used once.)
biz_id	String	The business ID used to query comparison results.
expired_time	Int	The timestamp that indicates the expiration time of the token.
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": 5,
    "token": "34fb21937e47ae719f11cbc719615687",
    "biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
    "request_id": "1462257147,3149525e-2c24-4862-8e9f-92040595f0a4",
    "expired_time": 1462257765
}

Failed request return example

{
    "error_message": "BAD_ARGUMENTS: return_url",
    "request_id": "1461740007,71eeb124-08f0-47b3-8fc8-ac048cfa1372",
    "time_used": 4
}

Error code list

ERROR_MESSAGE specific to GetToken

HTTP status code	error field	value	illustrate
400	error_message	IMAGE_ERROR_UNSUPPORTED_FORMA	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 or image_ref2. Note: The error message only contains one <param> that corresponds to the first image that meets the conditions. <param> is image_ref1 or image_ref2.
400	error_message	NO_FACE_FOUND	This error indicates that no face is detected in the uploaded image in image_ref[x].
400	error_message	INVALID_TOKEN	The token does not exist, has expired, is invalid, or is not returned by the API with the same API key.
400	error_message	MULTIPLE_FACES	This error indicates that multiple faces are detected in the uploaded image in image_ref[x].

General ERROR_MESSAGE

HTTP status code	error field	value	illustrate
403	error	AUTHENTICATION_ERROR	api_key and api_secret do not match.
403	error	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 <reason> include "Denied." (no permission to call this API).
403	error_message	CONCURRENCY_LIMIT_EXCEEDED	The concurrency limit is exceeded.
400	error_message	MISSING_ARGUMENTS:<key>	A required parameter is missing.
400	error_message	BAD_ARGUMENTS:<key>	An error occurred while parsing a parameter (for example, a parameter is a number but a non-numeric string is used, or the value is too long).
404	error	API_NOT_FOUND	The API does not exist.
500	error_message	INTERNAL_ERROR	Internal server error. If this error occurs, send the request again. If this persists, contact FaceID customer service or business support.