本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。
本文介绍活体检测方案PC或移动端H5网页认证方案的接入流程。
发起认证请求
接口名：InitFaceVerify。
全局接入地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）
请求方法：POST和GET。
传输协议：HTTPS。
接口说明：每次开始认证前通过本接口获取CertifyId，用来串联认证请求中的各个接口。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 认证场景ID。您可以在控制台创建认证场景后获得的场景ID，具体操作，请参见添加认证场景。 | 100000**** |
OuterOrderNo | String | 是 | 客户服务端自定义的业务唯一标识，用于后续定位排查问题使用。值最长为32位长度的字母数字组合，请确保唯一。 | e0c34a77f5ac40a5aa5e6ed20c****** |
ProductCode | String | 是 | 认证方案。 唯一取值：LR_FR。 | LR_FR |
Model | String | 是 | 要进行活体检测的类型。
| MULTI_ACTION |
ReturnUrl | String | 是 | 客户业务页面回跳的目标地址。 | http://www.aliyun.com |
MetaInfo | String | 是 | MetaInfo环境参数。实际环境需要通过JS文件，调用函数getMetaInfo()获取，详情请参见PC或移动端H5网页接入。 | {"zimVer":"3.0.0","appVersion": "1","bioMetaInfo": "4.1.0:1150****,0","appName": "com.aliyun.antcloudauth","deviceType": "ios","osVersion": "iOS 10.3.2","apdidToken": "","deviceModel": "iPhone9,1"} 说明 该示例仅供参考，实际集成中不能直接应用，否则会导致无法正常获取到认证URL。 |
Mobile | String | 否 | 用户手机号码。 | 130xxxxxxxx |
Ip | String | 否 | 用户IP。 | 114.XX.XX.XX |
UserId | String | 是 | 客户业务自定义的用户ID，请保持唯一。 | 12345**** |
CallbackUrl | String | 否 | 认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以 说明 仅当认证完成（包含认证通过和认证未通过）时才会触发回调，若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。 | https://www.aliyundoc.com |
CallbackToken | CallbackToken | 否 | 安全Token，由您自行生成，用于防重复、防篡改校验。 如果设置了该值会在回调地址显示CallbackToken字段。 | NMjvQanQgplBSaEI0sL86****** |
CertifyUrlType | String | 否 | Web SDK设备类型。取值WEB或者H5。 说明 只支持Web SDK设备类型。 | WEB |
CertifyUrlStyle | String | 否 | 返回certifyUrl类型，包括：
| L |
ProcedurePriority | String | 否 | 移动端H5方式认证出现WebRTC或者Webassembly不兼容时的降级配置。默认值：url。
说明 仅移动端H5认证方式支持降级。 本功能目前处于试用阶段，此配置默认不生效，如果您想试用此功能，请通过智能在线联系阿里云工程师。 | url |
FaceGuardOutput | String | 否 | 人脸保镖标签种类。 DeviceRisk：设备风险标签。
说明 | DeviceRisk |
返回数据
名称 | 类型 | 描述 | 示例值 |
RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF****** |
Message | String | 请求参数的响应信息。 | success |
Code | String | 返回码：200为成功，其他为失败。 | 200 |
ResultObject.CertifyId | String | 实人认证唯一标识。 警告 CertifyId字段为计费统计字段，为了方便后续核对账单，请您在本地留存该字段信息。 初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。 | 91707dc296d469ad38e4c5efa6****** |
ResultObject.CertifyUrl | String | Web认证URL，当您完成服务端初始化，阿里云会将Web认证URL返回给您。认证结束后根据请求参数中设置的ReturnUrl进行跳转。 说明 初始化接口返回的认证CertifyUrl在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。 | http://aliyundoc.com |
返回Code和Message说明
Code | Message | 描述 |
200 | success | 成功。 |
400 | 参数不能为空 | 参数不能为空。 |
401 | 参数非法 | 非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。 |
402 | 应用配置不存在 | 应用配置不存在。 |
404 | 认证场景配置不存在 | 认证场景配置不存在，请先在控制台上创建认证场景。 |
410 | 未开通服务 | 未开通OSS产品或未完成OSS读写授权，请登录控制台完成授权。关于开通OSS产品和完成OSS读写授权，请参见授权金融级实人认证访问OSS存储空间。 |
411 | RAM无权限 | 需要给RAM用户授予AliyunAntCloudAuthFullAccess的操作权限。 |
412 | 欠费中 | 金融级实人认证或OSS存在欠费，请充值后操作。 |
414 | 设备类型不支持 | 当前移动设备不支持刷脸认证，请更换设备后操作。 |
415 | SDK版本不支持 | 当前认证SDK版本不支持刷脸认证，请升级SDK后操作。 |
416 | 系统版本不支持 | 当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。 |
417 | 无法使用刷脸服务 | 当前身份信息比对源不可用。若信息正确，建议人工审核。 |
418 | 刷脸失败次数过多 | 当天刷脸认证次数过多，请明天再试。 |
500 | 系统错误 | 系统内部错误，请反馈工程师排查。 |
查询认证结果
接口名：DescribeFaceVerify。
全局接入地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）
请求方法：POST和GET。
传输协议：HTTPS。
接口说明：当您收到回调通知之后，可以在服务端通过该接口获取相应的认证状态和认证资料。
请求参数
名称 | 类型 | 是否必选 | 描述 | 示例值 |
SceneId | Long | 是 | 认证场景ID。 | 1000000006 |
CertifyId | String | 是 | 实人认证唯一标识。 | 91707dc296d469ad38e4c5efa6a0f24b |
返回数据
名称 | 类型 | 描述 | 示例值 |
RequestId | String | 请求ID。 | 130A2C10-B9EE-4D84-88E3-5384FF039795 |
Message | String | 请求消息的响应信息。 | success |
Code | String | 返回码。具体说明，请参见返回Code和Message。 | 200 |
ResultObject.Passed | String | 认证结果。取值：
说明 判断认证结果请以ResultObject.Passed字段为准。 | T |
ResultObject.SubCode | String | 认证结果描述。具体说明，请参见ResultObject.SubCode错误码说明。 说明 判断认证结果请以ResultObject.Passed字段为准。 | 200 |
ResultObject.DeviceRisk | String | 设备风险标签。 | VirtualBrowser 说明 多个设备风险标签以半角逗号（,）分隔。如需了解更多设备风险标签及其含义，请参见人脸保镖标签说明。 |
ResultObject.MaterialInfo | String | 认证主体附件信息，主要为图片类材料。 本参数取值中涉及的字段解释，请参见下文的返回示例。 | {"faceAttack": "F","faceOcclusion":"F","facialPictureFront": {"faceAttackScore": 0.00008597839769208804,"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","qualityScore": 99.93476867675781}, "procedurePriorityResult":"keep"} |
返回示例
ResultObject.MaterialInfo的JSON格式示例：
{
// 是否为攻击：攻击为T，非攻击为F。
"faceAttack": "T",
// 是否有脸部遮挡：有脸部遮挡为T，否则为F。
"faceOcclusion": "F",
// 认证的照片信息。
"facialPictureFront": {
// 人脸攻击分。
"faceAttackScore": 0.00008597839769208804,
// 照片存放客户上海区域的OSS里，此为照片的bucket名。
"ossBucketName": "cn-shanghai-aliyun-cloudauth-1260051251634779",
// 照片存放客户上海区域的OSS里，此为照片的文件名。
"ossObjectName": "verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg",
// 照片https地址，有效期15分钟，从查询时开始计时。
"pictureUrl": "http://cn-shanghai-aliyun-cloudauth-1260051251634779.oss-cn-shanghai.aliyuncs.com/verify/1260051251634779/03a081bd96328aedf83f635f39a50c57_0.jpeg?Expires=1625371140&OSSAccessKeyId=STS.NTX1ngfr6Acg2Pmnn2RYM****&Signature=Hw5BF9WxJs6wI68IxKs41cxCU8****&security-token=CAISjgJ1q6Ft5B2yfSjIr5ftetTTi60X9qGMMHbcim5nXtZhu7GT1Dz2IH1PdXFgA%2Bgds%2Fswmm5U7vgalrkqEcEdHRGdN5YpsM8LrlzwO1h2TGRsq%2B5qsoasPETOITyZtZagToeUZdfZfejXGDKgvyRvwLz8WCy%2FVli%2BS%2FOggoJmadJlNWvRL0AxZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO4gEWq4bHm5fCskKD1Qenk7FO%2B9uuc6LJNZc8YM1NNP6ux%2FFze6b71ypd1gNH7q8ejtYfpGyW5oHHWwIMvErYbbaMrIV1WwZ9Z7knHaVAq%2BXwnOBkuuXYnIns0BdLMuZOSD7YQI2wYWEwgBcxt78agAF%2FHZbelNLYWtipAu5X5oG1t22SqIr1p3TMK5FrjDIVeWOppcxeRXtU%2BjR7hGcwd25scGhiraoxTXV3sxw%2F6dhFSswQ37O4j%2B%2FrCPtiGauqn2ZMdMj%2FvYwKb6KmpQqa%2BtR%2F9cxhS6hoIQRq0SUIfyXl5ZUiZbTjW22iwuX%2BPwzVCw%3D%3D",
// 活体人脸质量分数。
"qualityScore": 99.93476867675781
// 降级标识字段（仅当deviceType是h5时返回）Keep-未降级；url-该笔认证用户触发了URL降级完成认证；video-该笔认证用户触发了视频降级完成认证
"procedurePriorityResult":"keep"
},
}ResultObject.SubCode错误码说明
具体说明，请参见ResultObject.SubCode错误码说明。
如果您有个性化需求，您可以根据业务情况，参考返回的比对分和阈值，自定义认证结果。
返回Code和Message说明
具体说明，请参见返回Code和Message。
- 本页导读