文档首页/ 人脸识别服务 FRS/ API参考/ API/ 活体检测
更新时间：2025-06-18 GMT+08:00
查看PDF
分享

活体检测

功能介绍

活体检测的功能是通过判断视频中的人物动作与传入动作列表是否一致来识别视频中人物是否为活体。如果有多张人脸出现，则选取最大的人脸进行判定。

前提条件：

请确保您已开通人脸识别服务，具体操作方法请参见申请服务。

约束限制：

  • 目前支持检测视频文件，或视频的Base64编码，不支持直接检测视频流，需要用户客户端自己获取视频流并保存成文件，然后调用活体检测接口。
  • 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。
  • application/json请求的body中，请使用标准Json格式。
  • Base64编码中请勿使用回车换行。
  • 系统不保存用户视频。
  • 具体的约束限制信息请参见约束与限制章节。

建议：

  • 建议帧率10fps～30fps。
  • 视频文件的大小建议客户端压缩到200KB~2MB。

URI

POST /v2/{project_id}/live-detect

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

项目ID，获取方法请参见获取项目ID/账号名/AK/SK。

请求参数

表2 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

用户Token。

Token认证就是在调用API的时候将Token加到请求消息头，从而通过身份认证，获得操作API的权限，响应消息头中X-Subject-Token的值即为Token。

Content-Type

是

String

发送的实体的MIME类型，参数值为“application/json”。
表3 请求Body参数

参数名

是否必选

参数类型

说明

video_url

与video_file、video_base64三选一

String
视频的URL路径，目前仅支持华为云上OBS的URL，且人脸识别服务有权限读取该OBS桶的数据。开通读取权限的操作请参见服务授权。视频要求：
  • 视频Base64编码后大小不超过8MB。
  • 限制视频时长1～15秒。
  • 建议帧率10fps～30fps。
  • 封装格式：mp4、avi、flv、webm、asf、mov。
  • 视频编码格式： h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。

video_file

与video_url、video_base64三选一

File
本地视频文件。上传文件时，请求格式为multipart。视频要求：
  • 视频文件大小不超过8MB，建议客户端压缩到200KB~2MB。
  • 限制视频时长1～15秒。
  • 建议帧率10fps～30fps。
  • 封装格式：mp4、avi、flv、webm、asf、mov。
  • 视频编码格式： h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。

video_base64

与video_file、video_url三选一

String
视频数据，Base64编码，要求：
  • Base64编码后大小不超过8MB，建议客户端压缩到200KB~2MB。
  • 限制视频时长1～15秒。
  • 建议帧率10fps～30fps。
  • 封装格式：mp4、avi、flv、webm、asf、mov。
  • 视频编码格式： h261、h263、h264、hevc、vc1、vp8、vp9、wmv3。

actions

是

String
动作代码顺序列表，英文逗号（,）分隔。建议单动作，目前支持的动作有：
  • 1：左摇头
  • 2：右摇头
  • 3：点头
  • 4：嘴部动作
  • 5：眨眼

action_time

否

String

该参数为动作时间数组拼接的字符串，数组的长度和actions的数量一致，每一项代表了对应次序动作的起始时间和结束时间，单位为距视频开始的毫秒数。

nod_threshold

否

double

该参数为点头动作幅度的判断门限，取值范围:[1,90]，默认为10，单位为度。该值设置越大，则越难判断为点头。

香港局点暂不支持设置此参数。

响应参数

状态码： 200

表4 响应Body参数

参数

参数类型

描述

video-result

video-result object

活体检测结果，VideoDetectResult结构见VideoDetectResult。

warning-list

Array of WarningList objects

警告信息列表，WarningList结构见WarningList。
表5 video-result

参数

参数类型

描述

alive

Boolean

是否是活体。

actions

Array of ActionsList objects

动作列表。

picture

String

检测出最大人脸的图片base64。
表6 ActionsList

参数

参数类型

描述

confidence

Double

置信度，取值范围0～1。

action

Integer

动作编号，取值范围：[1,2,3,4]，其中： 1：左摇头 2：右摇头 3：点头 4：嘴部动作 5：眨眼
表7 WarningList

参数

参数类型

描述

warningCode

Integer

警告ID。

warningMsg

String

告警消息。

状态码： 400

表8 响应Body参数

参数

参数类型

描述

error_code

String

调用失败时的错误码。 调用成功时无此字段。

error_msg

String

调用失败时的错误信息。 调用成功时无此字段。

请求示例

  • 请求样例（方式一：使用视频的BASE64编码） 
    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"
 }
  • 请求样例（方式二：使用视频文件） 
    POST https://{endpoint}/v2/{project_id}/live-detect
 Request Header: 
 X-Auth-Token: MIINRwYJKoZIhvcNAQcCoIINODCCDTQCAQExDT... 
  
 Request Body: 
 video_file: File(视频文件) 
 actions: 1,3,2
 action_time: 1000-3000,4000-7000,9000-12000
  • 请求样例（方式三：使用视频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"
 }

响应示例

状态码：200

成功响应样例 
{
  "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": []
}

状态码：400

失败响应样例 
{ 
   "error_code": "FRS.0701", 
   "error_msg": "Parse video data failed."
 }

状态码

状态码请参见状态码。

错误码

错误码请参见错误码。

父主题： API