调用ContrastFaceVerify接口对包含眨眼动作的视频进行实人认证。
传入视频要求
当您在进行实人认证的时候,请保证传入视频满足以下所有条件,否则会返回500报错。
格式:FFmpeg所支持的格式。例如,MOV、MP4、M4A、3GP及码率。
屏幕方向:目前不支持横屏视频。
动作:视频中必须包含眨眼动作。
时长:视频时长小于或者等于5秒,建议为2~3秒。
大小:小于或者等于10 MB。
分辨率:大于或者等于320*480像素,且小于或者等于1080P,即1920*1080像素。
接口说明
接口名:ContrastFaceVerify。
全局接入地址:cloudauth.aliyuncs.com(IPv4)或cloudauth-dualstack.aliyuncs.com(IPv6)
请求方法:POST和GET。
传输协议:HTTPS。
接口说明:通过带眨眼动作的视频进行实人认证。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景,请参见添加认证场景。 | 100000**** |
OuterOrderNo | String | 是 | 客户服务端自定义的业务唯一标识,用于后续定位排查问题使用。值最长为32位长度的字母数字组合,请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c35**** |
ProductCode | String | 是 | 认证方案。 唯一取值:ID_MIN_VIDEO。 | ID_MIN_VIDEO |
CertType | String | 是 | 用户证件类型。支持的证件类型,请参见方案概述。 不同证件类型,取值均为IDENTITY_CARD。 | IDENTITY_CARD |
CertName | String | 是 | 真实姓名。 | 张三 |
CertNo | String | 是 | 证件号码。 | 1******************9 |
OssBucketName | String | 是。在以下两种传入视频方式中,选择其中一种:
说明 如果选择OSS方式传入视频,您必须传入OssBucketName和OssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和Object名称。 | 已授权OSS空间的Bucket名称。 | cn-shanghai-aliyun-cloudauth-xxxxx |
OssObjectName | String | 已授权OSS空间的Object名称。 | verify/xxxxx/xxxxxx.jpeg | |
FaceContrastFileObject | InputStream | 本地视频文件。 | 具体接入方式,请参见Java SDK调用示例。 | |
Model | String | 否 | 活体检测类型。取值:
| FRONT_CAMERA_LIVENESS |
DeviceToken | String | 否 | 当前用户设备的Token,用于风险识别。 | McozS1ZWRcRZStlERcZZo_QOytx5jcgZoZJEoRLO**** |
Mobile | String | 否 | 用户手机号码。 | 1390000**** |
Ip | String | 否 | 用户IP。 | 114.100.XX.XX |
UserId | String | 否 | 客户业务自定义的用户ID。 | 148562088256**** |
EncryptType | String | 否 | 加密类型。为空表示不加密。 如开启加密传输,需设置加密算法。目前仅支持SM2国密算法。 如需传入加密算法,需对CertName和CertNo进行加密,并传入加密后的密文。有关参数加密的更多信息,请参见参数加密说明。 | SM2 |
返回参数
名称 | 类型 | 描述 | 示例值 |
RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 请求的响应信息。 | success |
Code | String | 返回码,200指接口响应成功。详细认证结果判断,请参见错误码。 | 200 |
ResultObject.Passed | String | 认证结果。取值:
说明 判断认证结果请以ResultObject.Passed字段为准。 | T |
ResultObject.CertifyId | String | 实人认证请求的唯一标识。 | 08573be80f944d95ac812e019e36**** |
ResultObject.SubCode | String | 认证结果描述,请参见下文ResultObject.SubCode错误码说明。 说明 判断认证结果请以ResultObject.Passed字段为准。 | 200 |
ResultObject.IdentityInfo | String | 认证的主体信息,目前支持的认证场景返回为空。 | xxx |
ResultObject.MaterialInfo | String | 认证主体附件信息,主要为图片类材料,JSON格式,请参见ResultObject.MaterialInfo的JSON格式示例。 说明 返回的图片为url_safebase64编码,图片转换时需要进行相反解码,即将-、_两个字符分别替换为+和/。 | {"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,
// 视频抽帧质量最佳人脸照片Base64编码。返回的图片为url_safebase64编码,图片转换时需要进行相反解码,即将-、_两个字符分别替换为+和/。
"pictureBase64": "_9j_4AAQSkZJRgABAQAAAQABAAD_2wX****",
// 活体人脸质量分数。
"qualityScore": 88.3615493774414,
// 人脸和公安比对分数,阈值可参考下表详细说明。
"verifyScore": 50.28594166529785
}
}
表 2. ResultObject.SubCode错误码说明
错误码 | 认证描述文案 | 是否计费 | 可能原因和处理建议 |
200 | 认证通过 | 是 | 成功。 |
201 | 姓名和身份证不一致 | 是 | 可能是用户的信息有误或用户的信息为假信息,建议用户确认后重新操作。若同一身份信息重新发起认证,服务端初始化将会返回417错误。 |
202 | 查询不到身份信息 | 是 | 可能是用户户口迁移等特殊状态导致,建议预留人工审核入口,进行人工审核。若同一身份信息重新发起认证,服务端初始化将会返回417错误。 |
203 | 查询不到照片或照片不可用 | 是 | 可能是公安库数据问题导致,建议预留人工审核入口,进行人工审核。若同一身份信息重新发起认证,服务端初始化将会返回417错误。 |
204 | 人脸比对不一致 | 是 | 可能不是同一人或活体照片质量较低,建议根据业务情况分层处理,若为同一人可重新操作。 |
205 | 活体检测存在风险 | 是 | 可能存在攻击风险,建议人工审核分层处理,若为真人可重新操作。 |
206 | 业务策略限制 | 是 | 为了保证认证的安全性,会对认证的设备、身份、人脸等环境进行安全检测,若检测到可能存在风险会判定认证结果不通过。您可以按照如下方法排查处理:
|
表 1. verifyScore阈值说明
千分之一误识率 | 万分之五误识率 | 万分之一误识率 | 十万分之五误识率 | 十万分之一误识率 |
70 | 71.5 | 75 | 76.5 | 80 |
如果您有个性化需求,您可以根据业务情况,参考返回的比对分和阈值,自定义认证结果。
返回Code和Message说明
Code | Message | 描述 |
200 | success | 请求响应成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
402 | 应用配置不存在 | 应用配置不存在。 |
404 | 认证场景配置不存在 | 认证场景配置不存在,请先在控制台上添加认证场景。具体操作,请参见添加认证场景。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权,请登录控制台完成授权。具体操作,请参见授权金融级实人认证访问OSS存储空间。 |
411 | RAM无权限 | 需要给子账号授予AliyunAntCloudAuthFullAccess的操作权限。 |
412 | 欠费中 | 金融级实人认证或OSS存在欠费,请充值后操作。 |
417 | 无法使用刷脸服务 | 当前身份信息比对源不可用。若信息正确,建议人工审核。 |
418 | 刷脸失败次数过多 | 当天刷脸认证次数过多,请在明天再试。 |
419 | 传入图片不可用 | 图片无法下载、图片内容为空、图片分辨率不符合要求或提取不到人脸特征,建议更换图片。 |
420 | 数据重复 | 通过多种方式传入了认证材料,目前支持以下两种方式中的一种传入认证材料:
|
421 | 传入图片过大 | 图片超过了10 MB,建议压缩图片或更换图片上传方式。 |
422 | 下载图片超时 | 图片下载超过了3秒,请排查网络后重新操作。 |
423 | 状态错误 | 传入的CertifyId认证状态需要为T(认证通过),您也可以更换其他方式传入图片。 |
430 | 视频读取失败 | 视频读取失败,建议参考视频要求重新提交。 |
431 | 视频过大 | 视频大小超过限制,建议参考视频要求,压缩视频后重新提交。 |
432 | 视频过长 | 视频长度超过限制,建议将录制视频时长控制在3秒内。 |
433 | 视频格式不支持 | 视频格式不支持,参考视频要求重新提交。 |
434 | 视频分辨率不符合要求 | 视频分辨率不支持,参考视频要求,调整分辨率后提交。 |
435 | 视频中无人脸 | 视频中检测不到人脸,建议参考视频要求重新提交。 |
500 | 系统错误 | 系统内部错误,请排查传入视频是否符合要求,具体信息,请参见传入视频要求。如果视频符合要求但仍然提示报错,请联系工程师处理。 |