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

传入图片格式要求

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

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

发起认证请求

接口名:ContrastFaceVerify

服务地址:cloudauth.aliyuncs.com。

请求方法:HTTPS POST和GET。

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

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

唯一取值:ID_MIN

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

当前仅支持身份证。

唯一取值:IDENTITY_CARD

IDENTITY_CARD
CertName String 真实姓名。 张三
CertNo String 证件号码。 330103xxxxxxxxxxxx
DeviceToken String 当前用户设备的Token,用于风险识别。 McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx
Mobile String 用户手机号码。 130xxxxxxxx
Ip String 用户IP。 114.xxx.xxx.xxx
UserId String 客户业务自定义的用户ID。 123456789
FaceContrastPicture String 照片Base64编码。
您可以在下述四种传入人脸照片方式中,选择其中一种:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS
说明
  • 如果您选择OSS方式传入人脸照片,您必须传入OssBucketNameOssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。
  • 如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。
/9j/4AAQSkZJRgABAQAASxxxxxxx
FaceContrastPictureUrl String OSS照片地址,目前只支持已授权的OSS照片地址。
您可以在下述四种传入人脸照片方式中,选择其中一种:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS
说明
  • 如果您选择OSS方式传入人脸照片,您必须传入OssBucketNameOssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。
  • 如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。
https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg
CertifyId String 之前实人认证通过的CertifyId,认证时的照片作为比对照片。
您可以在下述四种传入人脸照片方式中,选择其中一种:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS
说明
  • 如果您选择OSS方式传入人脸照片,您必须传入OssBucketNameOssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。
  • 如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。
0bfa7c493f850e5178b9f8613634c9xx
OssBucketName String 已授权OSS空间的Bucket名 。
您可以在下述四种传入人脸照片方式中,选择其中一种:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS
说明
  • 如果您选择OSS方式传入人脸照片,您必须传入OssBucketNameOssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。
  • 如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。
cn-shanghai-aliyun-cloudauth-xxxxx
OssObjectName String 已授权OSS空间的文件名。
您可以在下述四种传入人脸照片方式中,选择其中一种:
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS
说明
  • 如果您选择OSS方式传入人脸照片,您必须传入OssBucketNameOssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。
  • 如果您选择FaceContrastPicture(照片Base64编码)方式传入人脸照片,请注意检查照片大小,不要传入过大的照片;您可以通过OSS方式上传较大的人脸照片。
verify/xxxxx/xxxxxx.jpeg
返回参数
名称 类型 是否必选 描述 示例值
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.MaterialInfo String 认证主体附件信息,主要为图片类材料,使用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说明
Code Message 描述
200 success 请求响应成功。
400 参数不能为空 参数不能为空。
401 参数非法 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
402 应用配置不存在 应用配置不存在。
404 认证场景配置不存在 认证场景配置不存在,请先在控制台上创建认证场景。具体操作,请参见添加认证场景
410 未开通服务 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。
411 RAM无权限 需要给子账号授予AliyunAntCloudAuthFullAccess的操作权限。
412 欠费中 金融级实人认证或OSS存在欠费,请充值后操作。
417 无法使用刷脸服务 当前身份信息比对源不可用。若信息正确,建议人工审核。
418 刷脸失败次数过多 当天刷脸认证次数过多,请明天再试。
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 业务策略限制 个性化业务安全策略限制,如有疑问可咨询客服。
210 认证通过 通过产品安全策略综合判断,建议认证通过。
verifyScore阈值说明
千分之一误识率 万分之五误识率 万分之一误识率 十万分之五误识率 十万分之一误识率
70 71.5 75 76.5 80
说明 如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。

SDK使用说明

如需其他语言的SDK示例代码,您可以通过OpenAPI Explorer在线调试工具调试API接口。该工具会自动生成SDK示例代码。

Java SDK使用示例

  • Maven依赖 :
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-core</artifactId>
        <version>4.4.3</version>
    </dependency>
    <dependency>
        <groupId>com.aliyun</groupId>
        <artifactId>aliyun-java-sdk-cloudauth</artifactId>
        <version>2.0.22</version>
    </dependency>
  • 使用示例:
    DefaultProfile profile = DefaultProfile.getProfile(
                "cn-hangzhou",    // 固定为cn-hangzhou。
                "AccessKeyID",      // 您的AccessKey ID。
                "AccessKeySecret");  // 您的AccessKey Secret。
    IAcsClient client = new DefaultAcsClient(profile);
    ContrastFaceVerifyRequest request = new ContrastFaceVerifyRequest();
    // 固定值。
    request.setProductCode("ID_MIN");
    // 固定值。
    request.setCertType("IDENTITY_CARD");
    request.setCertName("姓名张三");
    request.setIp("用户IP地址");
    request.setMobile("用户手机号");
    request.setDeviceToken("通过设备指纹获取的deviceToken");
    request.setUserId("用户ID");
    request.setCertNo("18位身份证号");
    request.setOuterOrderNo("商户请求的唯一标识");
    request.setSceneId(10xxxxxxL);
    request.setModel("FRONT_CAMERA_LIVENESS");
    
    
    // 请在以下四种方式中选择其一。
    // 1.照片Base64编码。
    // 2.照片OSS bucket名和文件名。
    // 3.照片OSS的URL地址。
    // 4.已经实人认证通过的CertifyId。
    
    // 方式一:照片Base64。
    request.setFaceContrastPicture("人脸照片Base64编码");
    // 方式二:照片OSS bucket名和文件名。
    //request.setOssBucketName("cn-shanghai-aliyun-cloudauth-xxxxx");
    //request.setOssObjectName("verify/xxxxx/xxxxxx.jpeg");
    // 方式三:照片OSS的URL地址,公网可访问。
    //request.setFaceContrastPictureUrl("https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg")
    // 方式四:已经实人认证通过的CertifyId。
    //request.setCertifyId("0bfa7c493f850e5178b9f8613634c9xx");
    
    ContrastFaceVerifyResponse response = client.getAcsResponse(request);
    System.out.println(response.getCode());
    System.out.println(response.getMessage());
    System.out.println(response.getRequestId());
    System.out.println(response.getResultObject().getPassed());
    System.out.println(response.getResultObject().getMaterialInfo());
    System.out.println(response.getResultObject().getIdentityInfo());