Describe

This API uploads a video selfie for liveness detection. After the video is successfully uploaded, you can use the returned token_still to call the Raw-Verify API to obtain the comparison and liveness detection results. You can call this API if the apikey has passive liveness detection permissions of the API service. Otherwise, the API returns the error code 403 (AUTHORIZATION_ERROR:Denied).

Call URL

Singapore region ：https://api-sgp.megvii.com/faceid/lite/raw/validate_still

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	video	File	The video that the user uploads. The format and bitrate of the video must be supported by FFmpeg. The recommended video duration is 1 to 3 seconds. The video size cannot exceed 20 MB.
Optional	biz_no	String	The string used to identify a verification process. The maximum length is 128 characters. If you want to use this parameter, we recommend that you use the same biz_no for the API calls (such as Raw-ValidateStill and Raw-Verify) in the same verification process and use different biz_no for different verification processes.
Optional	liveness_preference	String	This parameter specifies the preferences that are applied to the liveness detection to make it less or more strict. • "none": No preference. This is the default value. •"still_strict": Perform strict liveness detection on the uploaded video. This setting increases the security level but may affect the pass rate. If you use other values, the error code 400 (BAD_ARGUMENTS) is returned. Note: This parameter applies to passive liveness detection. The strictness configurations for video liveness detection are in the verify API.
Optional	return_image	String	This parameter specifies whether to return the best-quality image of the video. Valid values: •0: Do not return image (default). • 1: Return 1 best-quality image (only if the API call is successful). •2: Return 2 best-quality images (only if the API call is successful).
Optional	return_multifaces_tag	String	This parameter specifies whether to return the multiple faces tag. 0: Do not return (default) 1: Return
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).

Return value description

Field	type	illustrate
request_id	String	The unique string to identify each request. This field is always returned.
time_used	Int	The time taken by the entire request in milliseconds. This field is always returned.
biz_no	String	This is returned only if the biz_no parameter is specified when you call this API, regardless of whether the request fails. The value is the same as the one you specify.
token_still	String	This field is returned only if the call is successful. The returned token is used to call the Raw-Verify API. The length of the value cannot exceed 1024 bytes. Note: The token is valid for 24 hours.
image_best	String	The field is returned if the call is successful and return_image is 1 or 2. The value of this field is the base64 string of the best-quality JPEG image that will be used for face comparison. In abnormal circumstances, the value of this field might be null.
image_best_2	String	This field is returned if the call is successful and return_image is 2. The value of this field is the base64 string of the other best-quality JPEG image. In abnormal circumstances (for example, if there is only one image that meets the quality requirements), the value of this field might be null.
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": 6206,
    "biz_no": "12345",
    "token_still": "68d32116d9ba2d2662812df30705dcb5",
    "request_id": "1491803871,dc23ec02-5ab5-48a4-8fe9-95f4eeb37699",
    "image_best": "data:image/jpeg;base64,..."
}

Failed request return example

{
    "time_used": 1,
    "error_message": "MISSING_ARGUMENTS: video",
    "request_id": "1491803987,5c52c7c6-e974-4c83-9f22-9d268d6e35b0"
}

Error code list

HTTP status code	error message	illustrate
400	VIDEO_FACE_NOT_FOUND	No face is detected in the uploaded video.
400	VIDEO_LOW_FACE_QUALITY	The image quality of the face in the uploaded video is low.
400	VIDEO_INVALID_DURATION	The video duration is invalid.
400	VIDEO_UNSUPPORTED_FORMAT	The video cannot be parsed. FFmpeg does not support the video format or the video is corrupted.
400	VIDEO_FACE_OCCLUDE	The face in the uploaded video is obstructed.

General ERROR_MESSAGE

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