LivenessFaceVerify-人脸静默活体检测

人脸静默活体(LivenessFaceVerify)指通过API接口传入提前获取的人脸图片进行真实人脸检测的服务。其算法主要识别人脸是否为屏幕翻拍、打印图片等活体攻击类型。该服务适用于低风险业务场景或配合离线人脸识别SDK使用。若您的业务对真实人脸安全要求较高,推荐您集成App或者WebSDK模式或者集成人脸Deepfake检测服务,辅助识别更多维度人脸伪造风险。

传入图片要求

为了确保模型效果稳定,您需要保证传入的图片中只有一张人脸,且该人脸的角度正常。此外,还需要满足以下条件:

  • 图片格式:JPG,JPEG。

  • 图片大小:推荐50~100KB,最大不超过1 MB。

  • 图片分辨率:建议640*480(高*宽),不超过1920*1080(高*宽),且保持照片的高大于宽。推荐短边缩放到720像素,压缩率0.8。

  • 图片质量:照片清晰、曝光正常,脸部无过黑、过亮、光晕等情况。

接口说明

  • 接口名:LivenessFaceVerify

  • 全局接入地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)

  • 请求方法:POSTGET

  • 传输协议:HTTPS

  • 接口说明:调用LivenessFaceVerify接口对人脸图片进行活体检测。

  • QPS限量:API独享QPS限量,详情请参见服务端接口QPS限量说明

请求参数

名称

类型

是否必选

描述

示例值

SceneId

Long

认证场景ID。该ID在控制台创建认证场景后自动生成。

100000****

OuterOrderNo

String

客户服务端自定义的业务唯一标识,用于后续定位排查问题。

取值最长为32位长度的字母数字组合,请确保唯一。

e0c34a77f5ac40a5aa5e6ed20c353888

ProductCode

String

固定值:LR_FR_MIN

LR_FR_MIN

FaceContrastPicture

String

说明

本方案提供三种传入人脸照片的方式,请您选择其中一种。

  • FaceContrastPicture

  • FaceContrastPictureUrl

  • OSS

如果您选择 OSS 方式传入人脸照片,您必须传入 OssBucketNameOssObjectName 参数。

OSS 请求参数仅支持开通实人认证服务时授权的OSS生成的 Bucket 和 Object 。

照片Base64编码。

/9j/4AAQSkZJRgABAQAASxxxxxxx

FaceContrastPictureUrl

String

人脸图片地址,公网可访问的HTTP、HTTPS链接。

https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg

OssBucketName

String

传入OSS存储空间(Bucket)名。需确保与授权OSS时的Bucket名一致。

cn-shanghai-aliyun-cloudauth-xxxxx

OssObjectName

String

传入OSS中照片的具体文件名。您可以登录OSS管理控制台,在目标文件的详情面板复制文件名。

verify/xxxxx/xxxxxx.jpeg

Model

String

活体检测类型。取值:

  • FRONT_CAMERA_LIVENESS:移动设备前置摄像头采集的人脸图片活体检测。

  • REAR_CAMERA_LIVENESS:其他场景采集的人脸图片活体检测。

FRONT_CAMERA_LIVENESS

DeviceToken

String

设备Token,用于风险识别。

McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx

Mobile

String

用户手机号码。

130xxxxxxxx

Ip

String

用户网络IP地址。

114.xxx.xxx.xxx

UserId

String

您自定义的用户ID(最长100个字符),请保持唯一。

123456789

Crop

String

是否允许裁剪人脸图片:

  • T:允许剪裁

  • F(默认):不允许剪裁

说明
  • 若您请求的图片并非来自标准活体检测SDK采集,建议您允许裁剪人脸图片。

  • 开启该功能后,将会对请求的图片先进行人脸裁剪与矫正,完成后会发起请求服务。

T

返回数据

名称

类型

描述

示例值

RequestId

String

请求ID。

130A2C10-B9EE-4D84-88E3-5384FF039795

Code

String

返回码。返回200表示响应成功。其他返回码说明,请参见返回CodeMessage说明

详细认证结果判断请参考ResultObject.SubCode的结果。

200

Message

String

返回信息的响应消息。

success

ResultObject.Passed

String

认证结果,取值:

  • T:通过

  • F:未通过

T

ResultObject.CertifyId

String

实人认证请求的唯一标识。

08573be80f944d95ac812e019e3655a

ResultObject.SubCode

String

认证结果描述。

您可以在ResultObject.SubCode错误码说明中查看不同状态码的描述和处理建议。

说明

判断认证结果请以 ResultObject.Passed 字段为准。

200

ResultObject.MaterialInfo

String

人脸认证主体附件信息

  • 人脸攻击检测结果及攻击分(faceAttack/faceAttackScore)

  • 人脸遮挡检测结果及质量分(faceOcclusion/qualityScore)

{
  "faceAttack": "T",
  "faceOcclusion": "F",
  "facialPictureFront": {
    "faceAttackScore": 0.00008597839769208804,
    "qualityScore": 99.93476867675781
  }
}

返回CodeMessage说明

Code

Message

描述

200

success

成功。

400

参数不能为空

参数不能为空。

401

参数非法

非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。

404

认证场景配置不存在

认证场景配置不存在,请先在控制台上创建认证场景。

410

未开通服务

未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。具体操作,请参见授权金融级实人认证访问OSS存储空间

411

RAM无权限

需要为子账号授予AliyunAntCloudAuthFullAccess的操作权限。

412

欠费中

金融级实人认证或OSS存在欠费,请充值后操作。

419

传入图片不可用

图片无法下载、图片内容为空、图片分辨率不符合要求或提取不到人脸特征,建议更换图片。

420

数据重复

图片传入方式超过了一种。支持以下三种传入人脸图片的方式,只能使用其中一种:

  • FaceContrastPicture

  • FaceContrastPictureUrl

  • OSS:OssBucketName、OssObjectName

421

传入图片过大

图片超过了1 MB,建议压缩图片或更换图片上传方式。

422

下载图片超时

图片下载超过了3秒,请排查网络后重新操作。

500

系统错误

系统内部错误,请反馈工程师排查。