调用ContrastFaceVerify接口通过传入图片进行实人认证。

传入图片格式要求

传入人脸图片时,支持人脸顺时针旋转90度、180度和270度,多人脸的情况会选取最大人脸。

当您在进行实人认证的时候,请传入满足以下所有条件的图片:

  • 认证主体的近期照片,人脸需要完整清晰无遮挡、表情自然且正对摄像头。
  • 照片清晰、曝光正常,脸部无过黑、过亮、光晕等情况、角度无太大偏差。
  • 分辨率不超过1920*1080(高*宽),至少为640*480,推荐短边缩放到720像素,压缩率大于0.9。照片高大于宽,如果传入的照片宽大于高,可能会影响检测效果。
  • 照片大小需要小于1 MB。
示例:示例

发起认证请求

接口名:ContrastFaceVerify

服务地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)

请求方法:POST和GET。

传输协议:HTTPS。

接口说明:通过传入图片进行实人认证。

请求参数
名称类型是否必选描述示例值
SceneIdLong认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景100000****
OuterOrderNoString客户服务端自定义的业务唯一标识,用于后续定位排查问题使用。值最长为32位长度的字母数字组合,请确保唯一。 e0c34a77f5ac40a5aa5e6ed20c35****
ProductCodeString认证方案。

唯一取值:ID_MIN

ID_MIN
ModelString活体检测类型。取值:
  • NO_LIVENESS:关闭活体检测。
  • FRONT_CAMERA_LIVENESS:移动设备前置摄像头采集的人脸照片活体检测。
  • REAR_CAMERA_LIVENESS:其他场景采集的人脸照片活体检测。
FRONT_CAMERA_LIVENESS
CertTypeString

用户证件类型。支持的证件类型,请参见方案概述

唯一取值:IDENTITY_CARD

IDENTITY_CARD
CertNameString真实姓名。张三
CertNoString证件号码。1******************9
DeviceTokenString当前用户设备的Token,用于风险识别。McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx
MobileString用户手机号码。1390000****
IpString用户IP。114.100.XX.XX
UserIdString客户业务自定义的用户ID。148562088256****
FaceContrastPictureString
说明 您需要在下述四种传入人脸照片方式中,选择其中一种:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS

如果您选择OSS方式传入人脸照片,您必须传入OssBucketNameOssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和Object。

照片Base64编码。如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。/9j/4AAQSkZJRgABAQAASxxxxxxx
FaceContrastPictureUrlString人像地址,公网可访问的HTTP、HTTPS链接。https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg
CertifyIdString之前实人认证通过的CertifyId,认证时的照片作为比对照片。您需要确保传入CertifyId关联的图片正常存储在授权的OSS Bucket中。0bfa7c493f850e5178b9f8613634****
OssBucketNameString已授权OSS空间的Bucket名称。cn-shanghai-aliyun-cloudauth-xxxxx
OssObjectNameString已授权OSS空间的Object名称。verify/xxxxx/xxxxxx.jpeg
CropString是否允许裁剪人脸图片,默认不允许。
  • T:表示允许剪裁。
  • F:表示不允许剪裁。
说明 若您请求的图片并非来自标准活体检测SDK采集,建议您允许裁剪人脸图片。

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

T
EncryptType String加密类型。为空表示不加密。

如开启加密传输,需传入加密算法。目前仅支持SM2国密算法。

如需传入加密算法,需对CertNameCertNo进行加密,并传入加密后的密文。有关参数加密的更多信息,请参见参数加密说明

SM2
返回参数
名称类型是否必选描述示例值
RequestIdString请求ID。130A2C10-B9EE-4D84-88E3-5384FF039795
MessageString请求的响应信息。success
CodeString返回码,200指接口响应成功。详细认证结果判断,请参见下文ResultObject.SubCode错误码说明200
ResultObject.PassedString认证结果。取值:
  • T:认证通过。
  • F:认证未通过。
说明 判断认证结果请以ResultObject.Passed字段为准。
T
ResultObject.SubCodeString认证结果描述,请参见ResultObject.SubCode错误码说明
说明 判断认证结果请以ResultObject.Passed字段为准。
200
ResultObject.IdentityInfoString认证的主体信息,目前支持的认证场景返回为空。null
ResultObject.MaterialInfoString认证主体附件信息,主要为图片类材料,使用JSON结构体转换的字符串表示,请参见ResultObject.MaterialInfo的JSON格式示例{"faceAttack": "F","faceOcclusion":"F","facialPictureFront": {"faceAttackScore": 0.00008597839769208804,"qualityScore": 88.3615493774414,"verifyScore": 50.28594166529785}}

ResultObject.MaterialInfo的JSON格式示例:

{
    // 是否为攻击:攻击为T,非攻击为F。
    "faceAttack": "F",
    // 是否有脸部遮挡:有脸部遮挡为T,否则为F。
    "faceOcclusion": "F",
    "facialPictureFront": {
         // 人脸攻击分。
         "faceAttackScore": 0.00008597839769208804,
         // 活体人脸质量分数。
        "qualityScore": 88.3615493774414,
        // 人脸和公安比对分数,阈值可参考下表详细说明。
        "verifyScore": 50.28594166529785
    }
}
返回Code和Message说明
CodeMessage描述
200success请求响应成功。
400参数不能为空参数不能为空。
401参数非法非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
402应用配置不存在应用配置不存在。
404认证场景配置不存在认证场景配置不存在,请先在控制台上创建认证场景。具体操作,请参见添加认证场景
410未开通服务未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
411RAM无权限需要给子账号授予AliyunAntCloudAuthFullAccess的操作权限。
412欠费中金融级实人认证或OSS存在欠费,请充值后操作。
417无法使用刷脸服务当前身份信息比对源不可用。若信息正确,建议人工审核。
418刷脸失败次数过多当天刷脸认证次数过多,请明天再试。
说明 一个身份信息在一天内最多可以认证失败20次,无法调整更多的认证失败次数。
419传入图片不可用图片无法下载、图片内容为空、图片分辨率不符合要求或提取不到人脸特征,建议更换图片。
420数据重复您通过多种方式传入了认证材料。目前支持以下四种方式中的一种传入认证材料:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • Oss
  • CertifyId
421传入图片过大图片超过了1 MB,建议压缩图片或更换图片上传方式。
422下载图片超时图片下载超过了3秒,请排查网络后重新操作。
423状态错误传入的CertifyId认证状态需要为T(认证通过),您也可以更换其他方式传入图片。
500系统错误系统内部错误,请通过智能在线联系阿里云工程师协助排查。
ResultObject.SubCode错误码说明
错误码认证描述文案是否计费可能原因和运营建议
200认证通过无。
201姓名和身份证不一致可能是用户的信息有误或用户的信息为假信息,建议用户确认后重新操作。若同一身份信息重复发起认证,服务端初始化将会返回417错误。
202查询不到身份信息可能是用户户口迁移等特殊状态导致,建议预留人工审核入口,进行人工审核。若同一身份信息重复发起认证,服务端初始化将会返回417错误。
203查询不到照片或照片不可用可能是公安库数据问题导致,建议预留人工审核入口,进行人工审核。若同一身份信息重复发起认证,服务端初始化将会返回417错误。
204人脸比对不一致可能不是同一人或活体照片质量较低,建议根据业务情况分层处理,若为同一人可重复操作。
205活体检测存在风险可能存在攻击风险,建议人工审核分层处理,若为真人可重复操作。
206业务策略限制
为了保证认证的安全性,会对认证的设备、身份、人脸等环境进行安全检测,若检测到可能存在风险会判定认证结果不通过。您可以按照如下方法排查处理:
  • 提醒用户卸载掉设备上可能安装的各种多开、分身、虚拟环境等软件或插件,恢复设备系统初始安全环境后重试。
  • 若是内部测试,可以在白名单设置页面加白处理。
209权威比对源异常可能存在权威比对源异常,无法比对。
210认证通过通过产品安全策略综合判断,建议认证通过。
verifyScore阈值说明
千分之一误识率万分之五误识率万分之一误识率十万分之五误识率十万分之一误识率
7071.57576.580
说明 如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。