本文介绍了活体检测方案的服务端接入流程。

接入方式说明

服务端接入支持以下两种方式:
  • 配合SDK调用发起认证请求InitFaceVerify)和查询认证结果DescribeFaceVerify)接口。
  • 无需与SDK配合,通过纯服务端调用人脸静默活体检测LivenessFaceVerify)接口。
    说明 如果您的业务场景无法通过SDK方式集成活体检测,推荐您选择人脸静默活体检测。人脸静默活体检测指对用户自拍图片或线下设备采集的用户人脸图片进行活体检测,适用于SDK无法覆盖的场景。

发起认证请求

接口名:InitFaceVerify

服务地址:cloudauth.aliyuncs.com

请求方法:HTTPS POST和GET。

接口说明:每次开始认证前通过本接口获取CertifyId,用来串联认证请求中的各个接口。

请求参数
名称 类型 是否必选 描述 示例值
SceneId Long 认证场景ID。 1000000006
OuterOrderNo String 客户服务端自定义的业务唯一标识,用于后续定位排查问题使用。值最长为32位长度的字母数字组合,请确保唯一。 e0c34a77f5ac40a5aa5e6ed20c353888
ProductCode String 认证方案。

唯一取值:LR_FR

LR_FR
Model String 活体检测类型。取值:
  • LIVENESS(默认):动作活体检测。
  • PHOTINUS_LIVENESS:动作活体+炫彩活体双重检测。
说明 仅Android SDK 1.2.6及以上版本、iOS SDK 1.2.4及以上版本支持设置活体检测模式。
LIVENESS
UserId String 客户业务自定义的用户ID,请保持唯一。 123456789
CertType String 证件类型。

当前仅支持身份证,必须传入IDENTITY_CARD

IDENTITY_CARD
CertName String 真实姓名。 张三
CertNo String 证件号码。 330103xxxxxxxxxxxx
MetaInfo String MetaInfo环境参数,需要通过客户端SDK获取。 {"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:11501568,0","appName": "com.aliyun.antcloudauth","deviceType": "ios","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"}
Mobile String 用户手机号码。 130xxxxxxxx
Ip String 用户网络IP。 114.xxx.xxx.xxx
CallbackUrl String 认证结果的回调通知地址,必须以https开头。

平台在完成认证后会回调该地址,并自动添加certifyIdpassedsubcode字段,示例:https://www.aliyun.com?certifyId=xxxx&passed=T&subcode=200

https://www.aliyun.com
CallbackToken String 安全Token,由您自行生成,用于防重复、防篡改校验。

如果设置了该值会在回调地址显示CallbackToken字段。

NMjvQanQgplBSaEI0sL86WnQplB
返回数据
名称 类型 描述 示例值
RequestId String 请求ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
Message String 返回信息。 success
Code String 返回码。200表示成功,其他表示失败。 200
ResultObject.CertifyId String 实人认证唯一标识。 91707dc296d469ad38e4c5efa6a0****
返回Code和Message说明
Code Message 描述
200 success 成功。
400 参数不能为空 参数不能为空。
401 参数非法 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
402 应用配置不存在 应用配置不存在。
404 认证场景配置不存在 认证场景配置不存在,请先在控制台上创建认证场景。
410 未开通服务 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
411 RAM无权限 需要为RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
412 欠费中 金融级实人认证或OSS存在欠费,请充值后操作。
414 设备类型不支持 当前移动设备不支持刷脸认证,请更换设备后操作。
415 SDK版本不支持 当前认证SDK版本不支持刷脸认证,请升级SDK后操作。
416 系统版本不支持 当前操作系统版本不支持刷脸认证,请升级系统或更换设备操作。
418 刷脸失败次数过多 当天刷脸认证次数过多,请明天再试。
500 系统错误 系统内部错误,请反馈工程师排查。

查询认证结果

接口名:DescribeFaceVerify

服务地址:cloudauth.aliyuncs.com

请求方法:HTTPS POST和GET。

接口说明:当接入方移动端收到回调之后,其服务端可以调用此接口,来获取相应的认证状态和认证资料。

请求参数
名称 类型 是否必选 描述 示例值
SceneId Long 认证场景ID。 1000000006
CertifyId String 实人认证唯一标识。 91707dc296d469ad38e4c5efa6a0****
返回数据
名称 类型 描述 示例值
RequestId String 请求ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
Message String 错误信息。 success
Code String 返回码。200表示接口响应成功。

详细认证结果判断请参见ResultObject.SubCode错误码说明

200
ResultObject.Passed String 认证结果。取值:
  • T:通过。
  • F:不通过。
说明 判断认证结果请以 ResultObject.Passed字段为准。
T
ResultObject.SubCode String 认证结果描述。
具体请参见 ResultObject.SubCode错误码说明
说明 判断认证结果请以 ResultObject.Passed字段为准。
200
ResultObject.IdentityInfo String 认证的主体信息,一般的认证场景返回为空。 null
ResultObject.DeviceToken String 设备Token。 McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx
ResultObject.MaterialInfo String 认证主体附件信息,主要为图片类材料。JSON格式,请参见ResultObject.MaterialInfo的JSON格式示例 {"faceAttack": "F","faceOcclusion": "F","facialPictureFront": {"faceAttackScore": 0.00008597839769208804,"qualityScore": 88.3615493774414,"pictureUrl": "https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg","ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779","ossObjectName": "verify/1260051251634779/6ba7bcfccf33f56cdb44ed086f36ce3e0.jpeg"}}

返回示例

ResultObject.MaterialInfo的JSON格式示例:
{
     // 是否为攻击:攻击为T,非攻击为F。
    "faceAttack": "F",    
     // 是否有脸部遮挡:有脸部遮挡为T,否则为F。
    "faceOcclusion": "F",
    // 认证的照片信息。
    "facialPictureFront": {
         // 人脸攻击分。
        "faceAttackScore": 0.00008597839769208804,
        // 活体人脸质量分数。
        "qualityScore": 88.3615493774414,
        // 照片https地址,有效期15分钟,从查询时开始计时。
        "pictureUrl": "https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg",
        // 照片存放客户上海区域的OSS里,此为照片的bucket名。
        "ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779",
        // 照片存放客户上海区域的OSS里,此为照片的文件名。
        "ossObjectName": "verify/1260051251634779/6ba7bcfccf33f56cdb44ed086f36ce3e0.jpeg"   
   }
}
ResultObject.SubCode错误码说明
错误码 认证描述文案 是否计费 可能原因和运营建议
200 认证通过 成功。
205 活体检测存在风险 可能存在攻击风险,建议人工审核分层处理,若为真人可重新操作。
206 业务策略限制 个性化业务安全策略限制,如有疑问可咨询客服。
返回Code和Message说明
Code Message 描述
200 success 成功。
400 参数不能为空 参数不能为空。
401 参数非法 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
403 认证未完成 认证未完成。
404 认证场景配置不存在 认证场景配置不存在,请先在控制台上创建认证场景。
406 无效的CertifyId 无效的CertifyId。
410 未开通服务 未开通OSS产品或未完成OSS读写授权。
411 RAM无权限 需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
424 身份认证记录不存在 该CertifyId还没有对应的身份认证提交记录。
500 系统错误 系统内部错误。

人脸静默活体检测

接口名:LivenessFaceVerify

服务地址:cloudauth.aliyuncs.com

请求方法:HTTPS POST和GET。

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

请求参数
名称 类型 是否必选 描述 示例值
SceneId Long 认证场景ID。 1000000006
OuterOrderNo String 客户服务端自定义的业务唯一标识,用于后续定位排查问题。取值最长为32位长度的字母数字组合,请确保唯一。 e0c34a77f5ac40a5aa5e6ed20c353888
ProductCode String 固定值:LR_FR_MIN LR_FR_MIN
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,请保持唯一。 123456789
FaceContrastPicture String 人脸图片的Base64编码。

请注意检查人脸图片大小,不要传入过大的人脸图片。您可以通过OSS方式上传较大的人脸图片。

说明 您必须选择以下一种方式传入人脸图片:
  • 人脸图片Base64编码:传入FaceContrastPicture
  • 人脸图片URL:传入FaceContrastPictureUrl
  • 通过OSS:传入OssBucketNameOssObjectName
/9j/4AAQSkZJRgABAQAASxxxxxxx
FaceContrastPictureUrl String OSS人脸图片地址。

仅支持开通实人认证服务时授权的OSS生成的URL。

说明 您必须选择以下一种方式传入人脸图片:
  • 人脸图片Base64编码:传入FaceContrastPicture
  • 人脸图片URL:传入FaceContrastPictureUrl
  • 通过OSS:传入OssBucketNameOssObjectName
https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg
OssBucketName String 已授权OSS空间的Bucket名。

仅支持开通实人认证服务时授权的OSS的Bucket和文件名。

说明 您必须选择以下一种方式传入人脸图片:
  • 人脸图片Base64编码:传入FaceContrastPicture
  • 人脸图片URL:传入FaceContrastPictureUrl
  • 通过OSS:传入OssBucketNameOssObjectName
cn-shanghai-aliyun-cloudauth-xxxxx
OssObjectName String 已授权OSS空间的文件名。

仅支持开通实人认证服务时授权的OSS的Bucket和文件名。

说明 您必须选择以下一种方式传入人脸图片:
  • 人脸图片Base64编码:传入FaceContrastPicture
  • 人脸图片URL:传入FaceContrastPictureUrl
  • 通过OSS:传入OssBucketNameOssObjectName
verify/xxxxx/xxxxxx.jpeg
返回数据
名称 类型 描述 示例值
RequestId String 请求ID。 130A2C10-B9EE-4D84-88E3-5384FF039795
Message String 请求消息的响应信息。 success
Code String 返回码。关于返回码的详细介绍,请参见返回Code和Message说明 200
ResultObject.Passed String 认证结果。取值:
  • T:认证通过。
  • F:认证未通过。
T
ResultObject.SubCode String 认证结果描述。具体请参见ResultObject.SubCode错误码说明 200
ResultObject.MaterialInfo String 认证主体附件信息,主要为图片类材料,JSON格式,具体请参见ResultObject.MaterialInfo的JSON格式示例 {"faceAttack":"F","faceOcclusion":"F","facialPictureFront":{"faceAttackScore":0.00008597839769208804,"qualityScore":88.3615493774414}}

返回示例

ResultObject.MaterialInfo的JSON格式示例:
{
    // 是否为攻击。T表示是,F表示否。
    "faceAttack": "F",
    // 是否有脸部遮挡。T表示是,F表示否。
    "faceOcclusion": "F",
    "facialPictureFront": {
         // 人脸攻击分。
         "faceAttackScore": 0.00008597839769208804,
         // 活体人脸质量分数。
        "qualityScore": 88.3615493774414
    }
}
返回Code和Message说明
Code Message 描述
200 success 成功。
400 参数不能为空 参数不能为空。
401 参数非法 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
404 认证场景配置不存在 认证场景配置不存在,请先在控制台上创建认证场景。
410 未开通服务 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
411 RAM无权限 需要为RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。
412 欠费中 金融级实人认证或OSS存在欠费,请充值后操作。
419 传入图片不可用 图片无法下载、图片内容为空、图片分辨率不符合要求或提取不到人脸特征,建议更换图片。
420 数据重复 图片传入方式超过了一种。支持以下三种传入人脸图片的方式,必须且只能使用其中一种:
  • 人脸图片Base64编码:传入FaceContrastPicture
  • 人脸图片URL:传入FaceContrastPictureUrl
  • 通过OSS:传入OssBucketNameOssObjectName
421 传入图片过大 图片超过了1 MB,建议压缩图片或更换图片上传方式。
422 下载图片超时 图片下载超过了3秒,请排查网络后重新操作。
500 系统错误 系统内部错误,请反馈工程师排查。
ResultObject.SubCode错误码说明
错误码 认证描述文案 是否计费 可能原因和运营建议
200 认证通过 无。
205 活体检测存在风险 可能存在攻击风险,建议人工审核分层处理。如果是真人,可重新操作。