如何通过InitFaceVerify接口进行活体人脸验证_实人认证(ID Verification)-阿里云帮助中心

本文介绍了如何通过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，用来串联认证请求中的各个接口。

QPS限量：API独享QPS限量，详情请参见服务端接口QPS限量说明。

请求参数

名称	类型	是否必选	描述	示例值
SceneId	Long	是	认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景，请参见添加认证场景。	100000****
OuterOrderNo	String	是	您自定义的业务唯一标识，用于后续定位排查问题使用。值最长为32位长度的字母和数字组合，请确保唯一。	e0c34a77f5ac40a5aa5e6ed20c35****
ProductCode	String	是	认证方案。唯一取值：PV_FV。	PV_FV
Model	String	否	活体检测类型。取值： LIVENESS（默认）：眨眼动作活体检测。 PHOTINUS_LIVENESS：眨眼动作活体+炫彩活体双重检测。 MULTI_ACTION：多动作活体检测。当前为眨眼+任意摇头检测。（顺序随机） MOVE_ACTION（推荐）：远近动作+眨眼动作活体检测。 MOVE_PHOTINUS：远近动作+炫彩活体检测。说明默认的活体检测类型在下列版本中支持： Android SDK1.2.6及以上 iOS SDK1.2.4及以上 Harmony SDK1.0.0及以上其他类型都在Android/iOS/Harmony的最新SDK版本上支持，建议集成最新版本使用。	MOVE_ACTION
UserId	String	是	您自定义的用户ID（最长100个字符），请保持唯一。	12345****
CertType	String	否	证件类型。当前仅支持身份证。唯一取值：IDENTITY_CARD。说明该方案中，不验证姓名和证件号码的真实性、一致性。如需验证，请选择实人认证方案。	IDENTITY_CARD
CertName	String	否	您的终端用户的真实姓名。	张三
CertNo	String	否	您的终端用户的证件号码。	33010312345678****
MetaInfo	String	是	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集成说明获取。
Mobile	String	否	您的终端用户的手机号码。	1304567****
Ip	String	否	您的终端用户的IP。	114.112.xx.xx
FaceContrastPicture	String	否金融级活体人脸验证方案提供四种传入人脸照片的方式，请您选择其中一种。 FaceContrastPicture FaceContrastPictureUrl CertifyId OSS：OssBucketName、OssObjectName	照片Base64编码。如果您选择FaceContrastPicture（照片Base64编码）方式传入人脸照片，请注意检查照片大小，不要传入过大的照片。说明如果您需要上传较大的人脸照片，请选择OSS方式。	/9j/4AAQSkZJRgABAQAASASBC****
FaceContrastPictureUrl	String		人像地址，公网可访问的HTTP、HTTPS链接。	https://cn-shanghai-aliyun-cloudauth-**.oss-cn-shanghai.aliyuncs.com/verify/**.jpeg
CertifyId	String		如果您之前已经通过实人认证，可使用实人认证唯一标识CertifyId，认证时的照片作为人脸比对照片。说明您需要确保传入CertifyId关联的图片正常存储在授权的OSS Bucket中。	0bfa7c493f850e5178b9f8613634****
OssBucketName	String		已授权OSS的存储空间（Bucket）名称。如果您选择OSS方式传入人脸照片，您必须传入OssBucketName和OssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。	cn-shanghai-aliyun-cloudauth-****
OssObjectName	String		已授权OSS存储空间的文件（Object）名称。如果您选择OSS方式传入人脸照片，您必须传入OssBucketName和OssObjectName参数。OSS请求参数格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和文件名。	verify/****.jpeg
CallbackUrl	String	否	认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以`https`开头。平台在完成认证后会回调该地址，并自动添加`certifyId`、`passed`字段，`passed`字段值返回的是subcode值，示例：`https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200`。说明仅当认证完成（包含认证通过和认证未通过）时才会触发回调，若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。	https://www.aliyun.com
CallbackToken	String	否	安全Token，由您自行生成，用于防重复、防篡改校验。如果设置了该值会在回调地址显示CallbackToken字段。	NMjvQanQgplBSaEI0sL86WnQplB
Crop	String	否	是否允许裁剪人脸图片，默认不允许。 T：表示允许剪裁。 F：表示不允许剪裁。说明若您请求的图片并非来自标准活体检测SDK采集，建议您允许裁剪人脸图片。开启该功能后，将会对请求的图片先进行人脸裁剪与矫正，完成后会发起请求服务。	T
AuthId	String	否	用户授权ID，最大长度为64位字符。	92d46b9e9e2d703f2897f350d5bd4149
SuitableType	String	否	适老化配置参数，针对每笔认证请求生效，您可以根据自有App的业务属性、客群分布、操作特性等条件对于每笔认证请求选择不同的参数，包括以下选项，默认为0。 0：不开启，表示当前认证请求不开启适老化。 1：开启，表示当前认证请求开启适老化。 2：用户选择。支持终端用户选择认证模式，产品引导页提供“开启认证”和“长辈认证模式”两种认证入口，当用户选择“长辈认证模式”系统进入适老化模式。说明适老化主要是通过增加语音提示、字体放大、UI优化等方式针对老年人或身体机能存在缺陷的群体提供友好操作体验的认证模式。仅Navite SDK支持适老化模式，SDK版本需要大于或等于2.2.5。开启适老化，人脸验证时间会变长。当移动设备开启系统无障碍模式，SDK不支持开启适老化模式。	0
FaceGuardOutput	String	否	人脸保镖标签种类。 DeviceRisk：设备风险标签。说明选择输出人脸保镖会产生额外的费用，具体费用，请参见计费概述。如果不需要输出人脸保镖标签，可以不传递参数或者传入空值。	DeviceRisk
AppQualityCheck	String	否	SDK是否开启人脸严格质量检测。 Y：开启。 N：不开启（默认）。说明若开启该参数，SDK需集成对应模块。受严格质量检测影响，会导致用户刷脸成功率下降。仅支持安卓SDK 2.3.24及以上版本。	N

说明

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

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

返回数据

名称	类型	是否必选	描述	示例值
RequestId	String	是	本次请求的ID。	130A2C10-B9EE-4D84-88E3-5384FF03****
Message	String	否	请求消息的响应信息。	success
Code	String	是	返回码。关于返回码的具体内容，请参见返回Code和Message说明。	200
ResultObject.CertifyId	String	否	实人认证唯一标识。警告 CertifyId字段为计费统计字段，为了方便后续核对账单，请您在本地留存该字段信息。初始化接口返回的认证CertifyId在30分钟有效且仅能认证提交一次，请您在有效期内应用，避免重复使用。	91707dc296d469ad38e4c5efa6a0****

返回Code和Message说明

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