本文介绍了如何通过InitFaceVerify接口进行活体人脸验证。

传入图片格式要求

当您的终端用户在进行实人认证的时候，请确保传入的照片满足以下所有条件：

  • 近期照片，人脸完整清晰无遮挡，表情自然，正对摄像头，角度无太大偏差。
  • 照片清晰、曝光正常，脸部无过黑、过亮、光晕等情况。
  • 照片的分辨率不超过1920*1080（高*宽），不低于640*480（高*宽），且照片的高大于宽。推荐短边缩放到720像素，压缩率大于0.9。
  • 照片小于1 MB。
  • 照片支持顺时针旋转90°、180°和270°。
  • 照片中有且只有一张人脸。
    说明 如果一张照片中存在多张人脸，默认会选取面积最大的人脸进行验证。
正确的图片示例：示例

发起认证请求

接口名：InitFaceVerify。

服务地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）

请求方法：POST和GET。

传输协议：HTTPS。

接口说明：每次开始认证前通过本接口获取CertifyId，用来串联认证请求中的各个接口。

请求参数
名称类型是否必选 描述示例值
SceneIdLong是认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景，请参见添加认证场景。100000****
OuterOrderNoString是您自定义的业务唯一标识，用于后续定位排查问题使用。

值最长为32位长度的字母和数字组合，请确保唯一。

e0c34a77f5ac40a5aa5e6ed20c35****
ProductCodeString是认证方案。

唯一取值：PV_FV。

PV_FV
ModelString否活体检测类型。取值：
  • LIVENESS（默认）：眨眼动作活体检测。
  • PHOTINUS_LIVENESS：眨眼动作活体+炫彩活体双重检测。
  • MULTI_ACTION：多动作活体检测。当前为眨眼+任意摇头检测。
说明 活体检测模式仅支持运行在Android SDK 1.2.6及以上版本和iOS SDK 1.2.4及以上版本；多动作活体检测模式仅支持运行在Android SDK 1.6.4及以上版本和iOS SDK 1.5.1及以上版本。
LIVENESS
UserIdString是您自定义的用户ID，请保持唯一。12345****
CertTypeString否证件类型。

当前仅支持身份证。唯一取值：IDENTITY_CARD。

说明 该方案中，不验证姓名和证件号码的真实性、一致性。如需验证，请选择实人认证方案。
IDENTITY_CARD
CertNameString否您的终端用户的真实姓名。张三
CertNoString否您的终端用户的证件号码。33010312345678****
MetaInfoString是MetaInfo环境参数。需要通过客户端SDK获取，详情请参见App（SDK）接入。{"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"}
重要 该示例仅供参考，实际集成中不能直接应用，具体参考SDK集成说明获取。
MobileString否您的终端用户的手机号码。1304567****
IpString否您的终端用户的IP。114.112.xx.xx
FaceContrastPictureString否
金融级活体人脸验证方案提供四种传入人脸照片的方式，请您选择其中一种。
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • CertifyId
  • OSS：OssBucketName、OssObjectName
照片Base64编码。如果您选择FaceContrastPicture（照片Base64编码）方式传入人脸照片，请注意检查照片大小，不要传入过大的照片。
说明 如果您需要上传较大的人脸照片，请选择OSS方式。
/9j/4AAQSkZJRgABAQAASASBC****
FaceContrastPictureUrlString人像地址，公网可访问的HTTP、HTTPS链接。https://cn-shanghai-aliyun-cloudauth-****.oss-cn-shanghai.aliyuncs.com/verify/****.jpeg
CertifyIdString如果您之前已经通过实人认证，可使用实人认证唯一标识CertifyId，认证时的照片作为人脸比对照片。
说明 您需要确保传入CertifyId关联的图片正常存储在授权的OSS Bucket中。
0bfa7c493f850e5178b9f8613634****
OssBucketNameString已授权OSS的存储空间（Bucket）名称。如果您选择OSS方式传入人脸照片，您必须传入OssBucketName和OssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。cn-shanghai-aliyun-cloudauth-****
OssObjectNameString已授权OSS存储空间的文件（Object）名称。如果您选择OSS方式传入人脸照片，您必须传入OssBucketName和OssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。verify/****.jpeg
CallbackUrlString否
认证结果的回调通知地址，必须以https开头。平台在完成认证后会回调该地址，并自动添加certifyId、passed字段，passed字段值返回的是subcode值，示例：https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200。
说明 仅当认证完成（包含认证通过和认证未通过）时才会触发回调，若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。
https://www.aliyun.com
CallbackTokenString否安全Token，由您自行生成，用于防重复、防篡改校验。

如果设置了该值会在回调地址显示CallbackToken字段。

NMjvQanQgplBSaEI0sL86WnQplB
CropString否是否允许裁剪人脸图片，默认不允许。
  • T：表示允许剪裁。
  • F：表示不允许剪裁。
说明 若您请求的图片并非来自标准活体检测SDK采集，建议您允许裁剪人脸图片。

开启该功能后，将会对请求的图片先进行人脸裁剪与矫正，完成后会发起请求服务。

T
AuthIdString否用户授权ID，最大长度为64位字符。92d46b9e9e2d703f2897f350d5bd4149
SuitableTypeString否
适老化配置参数，针对每笔认证请求生效，您可以根据自有App的业务属性、客群分布、操作特性等条件对于每笔认证请求选择不同的参数，包括以下选项，默认为0。
  • 0：不开启，表示当前认证请求不开启适老化。
  • 1：开启，表示当前认证请求开启适老化。
  • 2：用户选择。

    支持终端用户选择认证模式，产品引导页提供“开启认证”和“长辈认证模式”两种认证入口，当用户选择“长辈认证模式”系统进入适老化模式。

说明
  • 适老化主要是通过增加语音提示、字体放大、UI优化等方式针对老年人或身体机能存在缺陷的群体提供友好操作体验的认证模式。
  • 仅Navite SDK支持适老化模式，SDK版本需要大于或等于2.2.5。
  • 开启适老化，人脸验证时间会变长。
  • 当移动设备开启系统无障碍模式，SDK不支持开启适老化模式。
0
说明

OSS入参格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名 。关于如何查询授权的OSS，请参见接入流程 。

如果您选择FaceContrastPicture（照片Base64编码）方式传入人脸照片，请注意检查照片大小，不要传入过大的照片；您可以通过OSS方式上传较大的人脸照片。

返回数据
名称类型是否必选描述示例值
RequestIdString是本次请求的ID。130A2C10-B9EE-4D84-88E3-5384FF03****
MessageString否请求消息的响应信息。success
CodeString是返回码。关于返回码的具体内容，请参见返回Code和Message说明。200
ResultObject.CertifyIdString否实人认证唯一标识。
警告

CertifyId字段为计费统计字段，为了方便后续核对账单，请您在本地留存该字段信息。

初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。
 91707dc296d469ad38e4c5efa6a0****
返回Code和Message说明
CodeMessage描述
200success成功。
400参数不能为空参数不能为空。
401参数非法非法参数。传入的姓名、身份证号码长度必须符合国家标准且不得包含英文字母等特殊字符。
402应用配置不存在应用配置不存在。
404认证场景配置不存在认证场景配置不存在，请先在控制台上创建认证场景。
410未开通服务未开通OSS产品或未完成OSS读写授权，请登录金融级实人认证控制台完成授权。具体操作，请参见授权金融级实人认证访问OSS存储空间
411RAM无权限需要给RAM账号授予AliyunAntCloudAuthFullAccess的操作权限。
412欠费中金融级实人认证或OSS存在欠费，请充值后操作。
414设备类型不支持当前移动设备不支持刷脸认证，请更换设备后操作。
415SDK版本不支持当前认证SDK版本不支持刷脸认证，请升级SDK后操作。
416系统版本不支持当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。
417无法使用刷脸服务自定义比对源的图片人脸特征提取失败，建议更换图片上传。
418刷脸失败次数过多当天刷脸认证次数过多，请明天再试。
419传入图片不可用图片无法下载、图片内容为空或图片分辨率不符合要求。
420数据重复图片传入方式超过了一种。 支持以下四种传入人脸照片的方式，必须且只能使用其中一种：
  • FaceContrastPicture
  • FaceContrastPictureUrl
  • Oss
  • CertifyId
421传入图片过大图片超过了1 MB，建议压缩图片或更换图片上传方式。
422下载图片超时图片下载超过了3秒，请排查网络后重新操作。
423状态错误传入的CertifyId认证状态需要为T（认证通过），您也可以更换其他方式传入图片。
500系统错误系统内部错误，请反馈工程师排查。