本文介绍了调用LivenessDetect接口进行静默活体检测的方法。静默活体检测帮助您检测传入的图片和视频中人脸是否是直接拍摄。

请求方法:支持以HTTPS POST或GET方法发送请求。

接口描述:通过对输入的人脸图片和视频进行检测,判断图片中人脸是否是直接拍摄。

上传图片地址的说明:在传入图片时,您需要上传其对应的HTTP或OSS地址。

说明 必须传入公网可访问的HTTP地址,例如,http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg。

图片或视频限制:

  • 支持传入本地图片。传入本地图片时,可以使用图片的相对路径或绝对路径。
  • 单张图片大小请控制在2 MB及以下,避免算法拉取超时。
  • 视频大小不超过16 MB。
  • 视频格式支持:MP4、AVI、FLV、WMV、MOV和RM。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String LivenessDetect

要执行的操作。取值:LivenessDetect。

BizId String 39ecf51e-2f81-4dc5-90ee-ff86125b****

认证ID。标识一次认证任务的唯一ID,不超过64字符。

说明 发起不同的认证任务时需要更换不同的BizId。
BizType String LivenessDetectTest

使用实人认证服务的业务场景标识。关于如何通过控制台创建BizType,请参见添加认证场景

MediaCategory String VIDEO

认证的资源类型。取值:

  • IMAGE:图片。
  • VIDEO:视频。
MediaFile String \xxx\xxx.JPG

认证的本地资源文件。

如果您使用本地资源文件进行人脸静默活体检测,请参见SDK调用示例。目前该方式仅支持SDK调用。

说明 MediaUrl和MediaFile二选一。
MediaUrl String https://www.aliyun.com/test.mov

认证的资源地址。公网可访问的HTTP、HTTPS链接。

说明 MediaUrl和MediaFile二选一。

返回数据

名称 类型 示例值 描述
Code String 200

返回码。取值:

Message String success

请求信息的响应消息。

RequestId String 473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E

本次请求ID。

ResultObject Struct

结果信息。

FrameUrl String http://cloudauth-zhangjiakou-new.oss-cn-zhangjiakou.aliyuncs.com/pre/hammal/1260051251634779/a545f594ed12444fa3c7bcceb0c67df4/04935c45f00e3a2.webm-frames/f00001.jpg?Expires=1603877940&OSSAccessKeyId=H4sp5QfNbuDg****&Signature=BMZu2%2FfpJmj2blcVIyabcJmQRgc%3D

截帧的图片链接。

说明 当传入的MediaCategory为VIDEO时,返回该参数。
Passed String T

静默活体检测是否通过。取值:

  • T:检测通过。
  • F:检测不通过。
Score Float 0.4312818

静默活体检测结果的分值。取值范围为0~1,阈值为0.82分。

  • 当分值小于0.82分,则ResultObject.Passed返回T。
  • 当分值大于或等于0.82分,则ResultObject.Passed返回F。
Success Boolean true

是否成功响应。

  • true:响应成功。
  • false:响应失败。

示例

请求示例

http(s)://[Endpoint]/?Action=LivenessDetect
&BizId=39ecf51e-2f81-4dc5-90ee-ff86125b****
&BizType=LivenessDetectTest
&MediaCategory=VIDEO
&MediaFile=FileInputStream
&MediaUrl=https://www.aliyun.com/test.mov
&<公共请求参数>

正常返回示例

XML格式

<LivenessDetectResponse>
      <ResultObject>
            <Passed>T</Passed>
            <Score>0.4312818</Score>
            <FrameUrl>http://cloudauth-zhangjiakou-new.oss-cn-zhangjiakou.aliyuncs.com/pre/hammal/1260051251634779/a545f594ed12444fa3c7bcceb0c67df4/04935c45f00e3a2.webm-frames/f00001.jpg?Expires=1603877940&amp;OSSAccessKeyId=H4sp5QfNbuDg****&amp;Signature=BMZu2%2FfpJmj2blcVIyabcJmQRgc%3D</FrameUrl>
      </ResultObject>
      <Message>Error.InternalError</Message>
      <RequestId>473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E</RequestId>
      <Code>200</Code>
  </LivenessDetectResponse>

JSON格式

{
    "ResultObject": {
        "Passed": "T",
        "Score": "",
        "FrameUrl": "http://cloudauth-zhangjiakou-new.oss-cn-zhangjiakou.aliyuncs.com/pre/hammal/1260051251634779/a545f594ed12444fa3c7bcceb0c67df4/04935c45f00e3a2.webm-frames/f00001.jpg?Expires=1603877940&OSSAccessKeyId=H4sp5QfNbuDg****&Signature=BMZu2%2FfpJmj2blcVIyabcJmQRgc%3D"
    },
    "Message": "Error.InternalError",
    "RequestId": "473469C7-AA6F-4DC5-B3DB-A3DC0DE3C83E",
    "Code": "200"
}

错误码

HttpCode 错误码 错误信息 描述
400 ParameterIsNull The parameter must not be empty. 参数不能为空。
401 InvalidParameter The specified parameter is invalid. 非法参数。
403 NoPermission This RAM user has no permissions to access API. 该RAM用户无权访问API。
410 NoSubscribeService OSS is not activated or you have not granted OSS the read write permission. 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
412 InDebt You have an outstanding payment. Please add funds first and try again. 实人认证存在欠费,请充值后再进行操作。
421 ResourcesTooLarge The size of the incoming resources are too large. 传入资源超过了最大限制。
422 DownloadTimedOut Downloading resource timed out. 下载资源超时(3秒)。
435 NoFaceDetected No face is detected in either the image or the video. 图片或者视频中检测不到人脸信息。
500 SystemError A system error occurred. 系统内部错误。

访问错误中心查看更多错误码。