本文介绍了活体检测方案的服务端接入流程。
接入方式说明
发起认证请求
接口名:InitFaceVerify。
服务地址:cloudauth.aliyuncs.com
。
请求方法:HTTPS POST和GET。
接口说明:每次开始认证前通过本接口获取CertifyId,用来串联认证请求中的各个接口。
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
SceneId | Long | 是 | 认证场景ID。 | 1000000006 |
OuterOrderNo | String | 是 | 客户服务端自定义的业务唯一标识,用于后续定位排查问题使用。值最长为32位长度的字母数字组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c353888 |
ProductCode | String | 是 | 认证方案。
唯一取值:LR_FR。 |
LR_FR |
Model | String | 否 | 活体检测类型。取值:
说明 仅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 |
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
RequestId | String | 是 | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 否 | 返回信息。 | success |
Code | String | 是 | 返回码。200表示成功,其他表示失败。 | 200 |
ResultObject.CertifyId | String | 否 | 实人认证唯一标识。 | 91707dc296d469ad38e4c5efa6a0**** |
Code | Message | 描述 |
---|---|---|
200 | success | 成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
402 | 应用配置不存在 | 应用配置不存在。 |
404 | 认证场景配置不存在 | 认证场景配置不存在,请先在控制台上创建认证场景。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。 |
411 | RAM无权限 | 需要为子账号授予AliyunAntCloudAuthFullAccess的操作权限。 |
412 | 欠费中 | 金融级实人认证或OSS存在欠费,请充值后操作。 |
414 | 设备类型不支持 | 当前移动设备不支持刷脸认证,请更换设备后操作。 |
415 | SDK版本不支持 | 当前认证SDK版本不支持刷脸认证,请升级SDK后操作。 |
416 | 系统版本不支持 | 当前操作系统版本不支持刷脸认证,请升级系统或更换设备操作。 |
418 | 刷脸失败次数过多 | 当天刷脸认证次数过多,请明天再试。 |
500 | 系统错误 | 系统内部错误,请反馈工程师排查。 |
- 通过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.20</version> </dependency>
- 使用示例:
DefaultProfile profile = DefaultProfile.getProfile( "cn-hangzhou", // 固定为cn-hangzhou。 "AccessKeyID", // 您的AccessKey ID。 "AccessKeySecret"); // 您的AccessKey Secret。 IAcsClient client = new DefaultAcsClient(profile); InitFaceVerifyRequest request = new InitFaceVerifyRequest(); request.setMetaInfo("MetaInfo环境参数"); request.setCertName("姓名张三"); request.setCertNo("18位身份证号"); // 固定值。 request.setCertType("IDENTITY_CARD"); request.setSceneId(10xxxxxxL); request.setOuterOrderNo("商户请求的唯一标识"); // 固定值。 request.setProductCode("LR_FR"); request.setModel("LIVENESS"); InitFaceVerifyResponse response = client.getAcsResponse(request); System.out.println(response.getCode()); System.out.println(response.getMessage()); System.out.println(response.getRequestId()); System.out.println(response.getResultObject().getCertifyId());
查询认证结果
接口名: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 | 是 | 认证结果。取值:
说明 判断认证结果请以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"}} |
返回示例
{
// 是否为攻击:攻击为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"
}
}
错误码 | 认证描述文案 | 是否计费 | 可能原因和运营建议 |
---|---|---|---|
200 | 认证通过 | 是 | 成功。 |
205 | 活体检测存在风险 | 是 | 可能存在攻击风险,建议人工审核分层处理,若为真人可重新操作。 |
206 | 业务策略限制 | 是 | 个性化业务安全策略限制,如有疑问可咨询客服。 |
Code | Message | 描述 |
---|---|---|
200 | success | 成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
403 | 认证未完成 | 认证未完成。 |
404 | 认证场景配置不存在 | 认证场景配置不存在,请先在控制台上创建认证场景。 |
406 | 无效的CertifyId | 无效的CertifyId。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权。 |
411 | RAM无权限 | 需要给子账号授予AliyunAntCloudAuthFullAccess的操作权限。 |
424 | 身份认证记录不存在 | 该CertifyId还没有对应的身份认证提交记录。 |
500 | 系统错误 | 系统内部错误。 |
- 通过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.20</version> </dependency>
- 使用示例:
DefaultProfile profile = DefaultProfile.getProfile( "cn-hangzhou", // 固定为cn-hangzhou。 "AccessKeyID", // 您的AccessKey ID。 "AccessKeySecret"); // 您的AccessKey Secret。 IAcsClient client = new DefaultAcsClient(profile); DescribeFaceVerifyRequest request = new DescribeFaceVerifyRequest(); request.setCertifyId("服务端初始化返回的CertifyId"); request.setSceneId(100000xxxxL); DescribeFaceVerifyResponse 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().getSubCode()); System.out.println(response.getResultObject().getMaterialInfo()); System.out.println(response.getResultObject().getIdentityInfo()); System.out.println(response.getResultObject().getDeviceToken());
人脸静默活体检测
接口名: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 |
DeviceToken | String | 否 | 设备Token,用于风险识别。 | McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLOxxxxxxx |
Mobile | String | 否 | 用户手机号码。 | 130xxxxxxxx |
Ip | String | 否 | 用户网络IP地址。 | 114.xxx.xxx.xxx |
UserId | String | 否 | 客户业务自定义的用户ID,请保持唯一。 | 123456789 |
FaceContrastPicture | String | 否 | 人脸图片的Base64编码。
请注意检查人脸图片大小,不要传入过大的人脸图片。您可以通过OSS方式上传较大的人脸图片。 说明 您必须选择以下一种方式传入人脸图片:
|
/9j/4AAQSkZJRgABAQAASxxxxxxx |
FaceContrastPictureUrl | String | 否 | OSS人脸图片地址。
仅支持开通实人认证服务时授权的OSS生成的URL。 说明 您必须选择以下一种方式传入人脸图片:
|
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的Bucket和文件名。 说明 您必须选择以下一种方式传入人脸图片:
|
verify/xxxxx/xxxxxx.jpeg |
名称 | 类型 | 是否必选 | 描述 | 示例值 |
---|---|---|---|---|
RequestId | String | 是 | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 否 | 错误信息。 | success |
Code | String | 是 | 返回码。取值:
详细认证结果判断请参考ResultObject.SubCode的结果。 |
200 |
ResultObject.Passed | String | 是 | 认证结果。取值:
|
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}} |
返回示例
{
// 是否为攻击。T表示是,F表示否。
"faceAttack": "F",
// 是否有脸部遮挡。T表示是,F表示否。
"faceOcclusion": "F",
"facialPictureFront": {
// 人脸攻击分。
"faceAttackScore": 0.00008597839769208804,
// 活体人脸质量分数。
"qualityScore": 88.3615493774414
}
}
Code | Message | 描述 |
---|---|---|
200 | success | 成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
404 | 认证场景配置不存在 | 认证场景配置不存在,请先在控制台上创建认证场景。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。 |
411 | RAM无权限 | 需要为子账号授予AliyunAntCloudAuthFullAccess的操作权限。 |
412 | 欠费中 | 金融级实人认证或OSS存在欠费,请充值后操作。 |
419 | 传入图片不可用 | 图片无法下载、图片内容为空、图片分辨率不符合要求或提取不到人脸特征,建议更换图片。 |
420 | 数据重复 | 图片传入方式超过了一种。支持以下三种传入人脸图片的方式,必须且只能使用其中一种:
|
421 | 传入图片过大 | 图片超过了1 MB,建议压缩图片或更换图片上传方式。 |
422 | 下载图片超时 | 图片下载超过了3秒,请排查网络后重新操作。 |
500 | 系统错误 | 系统内部错误,请反馈工程师排查。 |
错误码 | 认证描述文案 | 是否计费 | 可能原因和运营建议 |
---|---|---|---|
200 | 认证通过 | 是 | 无。 |
205 | 活体检测存在风险 | 是 | 可能存在攻击风险,建议人工审核分层处理。如果是真人,可重新操作。 |
- 通过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.20</version> </dependency>
- 使用示例:
DefaultProfile profile = DefaultProfile.getProfile( "cn-hangzhou", // 固定为cn-hangzhou。 "AccessKeyID", // 您的AccessKey ID。 "AccessKeySecret"); // 您的AccessKey Secret。 IAcsClient client = new DefaultAcsClient(profile); LivenessFaceVerifyRequest request = new LivenessFaceVerifyRequest(); // 固定值。 request.setProductCode("LR_FR_MIN"); // 固定值。 request.setModel("FRONT_CAMERA_LIVENESS"); request.setOuterOrderNo("商户请求的唯一标识"); request.setSceneId(10xxxxxxL); // 请在以下方式中选择一种,传入人脸图片。 // 方式一:人脸图片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") LivenessFaceVerifyResponse 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().getSubCode()); System.out.println(response.getResultObject().getMaterialInfo());
在文档使用中是否遇到以下问题
更多建议
匿名提交