调用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 | 否 | 活体检测类型。取值:
|
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编码。
您可以在下述四种传入人脸照片方式中,选择其中一种:
说明
|
/9j/4AAQSkZJRgABAQAASxxxxxxx |
FaceContrastPictureUrl | String | 是 | OSS照片地址,目前只支持已授权的OSS照片地址。
您可以在下述四种传入人脸照片方式中,选择其中一种:
说明
|
https://cn-shanghai-aliyun-cloudauth-xxxxxx.oss-cn-shanghai.aliyuncs.com/verify/xxxxx/xxxxx.jpeg |
CertifyId | String | 是 | 之前实人认证通过的CertifyId,认证时的照片作为比对照片。
您可以在下述四种传入人脸照片方式中,选择其中一种:
说明
|
0bfa7c493f850e5178b9f8613634c9xx |
OssBucketName | String | 是 | 已授权OSS空间的Bucket名 。
您可以在下述四种传入人脸照片方式中,选择其中一种:
说明
|
cn-shanghai-aliyun-cloudauth-xxxxx |
OssObjectName | String | 是 | 已授权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 | 是 | 认证结果。取值:
说明 判断认证结果请以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 | 数据重复 | 您通过多种方式传入了认证材料。目前支持以下四种方式中的一种传入认证材料:
|
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());
在文档使用中是否遇到以下问题
更多建议
匿名提交