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

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.