Help Center/ Face Recognition Service/ API Reference/ APIs/ Face LiveDetect

Updated on 2024-05-20 GMT+08:00

View PDF

Face LiveDetect

Function

This API is used to determine whether a person in a video is alive by checking whether the person's actions in the video are consistent with those in the input action list. If multiple faces appear, the largest face is selected.

Prerequisites:

Ensure that you have enabled FRS. For detailed operations, see Applying for FRS.

Restrictions:

Currently, only video files and Base64-encoded videos can be detected. User clients need to obtain the video streams, save them as files, and then call the LiveDetect API.
The size of a video file cannot exceed 8 MB. It is recommended that the video file be compressed to 200 KB to 2 MB on the client.
Use standard JSON format in the body of the application/json request.
Do not use carriage return characters in Base64 code.
The system does not save videos of users.
For details about other restrictions, see Restrictions and Limitations.

Suggestions:

The recommended frame rate is 10 fps to 30 fps.
It is recommended that the video file be compressed to 200 KB to 2 MB on the client.

URI

POST /v2/{project_id}/live-detect

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the ID, see Obtaining the Project ID/Account Name/AK/SK.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	User token. During API authentication using a token, the token is added to requests to obtain permissions for calling the API. The value of X-Subject-Token in the response header is the obtained token.
Content-Type	Yes	String	MIME type of the request body. The value is application/json.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
video_url	Either video_url, video_file, or video_base64 is mandatory.	String	Video URL. Currently, only the URL of an OBS bucket on Huawei Cloud is supported and FRS must have the permission to read data in the OBS bucket. For details about how to enable the read permission, see Service Authorization. The video requirements are as follows: The video size after Base64 encoding cannot exceed 8 MB. The video duration must be 1 to 15 seconds. The recommended frame rate is 10 fps to 30 fps. The encapsulation format can be MP4, AVI, FLV, WEBM, ASF, or MOV. The video encoding format can be H.261, H.263, H.264, HEVC, VC-1, VP8, VP9, or WMV3.
video_file	Either video_file, video_url, or video_base64 is mandatory.	File	Local video file. The request format is Multipart. The video requirements are as follows: The size of a video file cannot exceed 8 MB. It is recommended that the video file be compressed to 200 KB to 2 MB on the client. The video duration must be 1 to 15 seconds. The recommended frame rate is 10 fps to 30 fps. The encapsulation format can be MP4, AVI, FLV, WEBM, ASF, or MOV. The video encoding format can be H.261, H.263, H.264, HEVC, VC-1, VP8, VP9, or WMV3.
video_base64	Either video_base64, video_url, or video_file is mandatory.	String	Video data (Base64-encoded). Its requirements are as follows: The video size after Base64 encoding cannot exceed 8 MB. It is recommended that the video file be compressed to 200 KB to 2 MB on the client. The video duration must be 1 to 15 seconds. The recommended frame rate is 10 fps to 30 fps. The encapsulation format can be MP4, AVI, FLV, WEBM, ASF, or MOV. The video encoding format can be H.261, H.263, H.264, HEVC, VC-1, VP8, VP9, or WMV3.
actions	Yes	String	Action code sequence list. Actions are separated by commas (,). Currently, the following actions are supported: 1: Turning the face to the left 2: Turning the face to the right 3: Head nodding 4: Mouth movement
action_time	No	String	String of the action time array. The length of the array is the same as the number of actions. Each item contains the start time and end time of the action in the corresponding sequence. The unit is the milliseconds from the video start time.
nod_threshold	No	Double	Threshold for determining the amplitude of a nod action, in degrees. The value ranges from 1 to 90. The default value is 10. A larger value indicates more difficulties in determining whether an action is a nod. This parameter is not supported for Hong Kong sites.

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
video-result	video-result object	LiveDetect result. For details, see VideoDetectResult.
warning-list	Array of WarningList objects	Warning information list. For details, see WarningList.

**Table 5** video-result
Parameter	Type	Description
alive	Boolean	Whether a living figure is detected
actions	Array of ActionsList objects	Action list
picture	String	Base64 code of the image in which the maximum face is detected

**Table 6** ActionsList
Parameter	Type	Description
confidence	Double	Confidence level. The value ranges from 0 to 1.
action	Integer	Action ID. Possible values are as follows: 1: turning face to the left; 2: turning face to the right; 3: head nodding; 4: mouth movement.

**Table 7** WarningList
Parameter	Type	Description
warningCode	Integer	Warning ID
warningMsg	String	Warning message

Status code: 400

**Table 8** Response body parameters
Parameter	Type	Description
error_code	String	Error code when calling the API failed. This parameter is not included when the API is successfully called.
error_msg	String	Error message returned after the API fails to be called. This parameter is not included when the API is successfully called.

Example Requests

Example request (Method 1: Use the Base64 encoded string of a video.)

POST https://{endpoint}/v2/{project_id}/live-detect
 Request Header: 
 Content-Type: application/json 
 X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... 
  
 Request Body: 
 { 
    "video_base64":"/9j/4AAQSkZJRgABAgEASABIAAD", 
    "actions":"1,3,2",
    "action_time":"1000-3000,4000-7000,9000-12000"
 }

Example request (Method 2: Use a video file.)

POST https://{endpoint}/v2/{project_id}/live-detect
 Request Header: 
 X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... 
  
 Request Body: 
 video_file: File (Video file)
 actions: 1,3,2
 action_time: 1000-3000,4000-7000,9000-12000

Example request (Method 3: Use the video URL.)

POST https://{endpoint}/v2/{project_id}/live-detect
 Request Header: 
 Content-Type: application/json 
 X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... 
  
 Request Body: 
 { 
    "video_url":"/BucketName/ObjectName", 
    "actions":"1,3,2",
    "action_time":"1000-3000,4000-7000,9000-12000"
 }

Example Responses

Status code: 200

Example response for a successful request

{
  "video-result": {
    "alive": true,
    "actions": [{
        "action": 1,
        "confidence": 0.823
      },{
        "action": 3,
        "confidence": 0.823
      },{
        "action": 2,
        "confidence": 0.823
      }],
    "picture": "/9j/4AAQSkZJRgABAQEAYABgAAD/2w..."
  },
  "warning-list": []
}

Status code: 400

Example response for a failed request

{ 
   "error_code": "FRS.0701", 
   "error_msg": "Parse video data failed."
 }

Status Codes

See Status Codes.

Error Codes

See Error Codes.

Parent topic: APIs

Previous topic: Face Verification

Next topic: Face Retrieval

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot