AI 助理
文档备案控制台
官方文档
首页

InitFaceVerify-发起认证请求

更新时间：
复制 MD 格式
产品详情
我的收藏

本文介绍如何通过调用InitFaceVerify接口发起金融级多因子意愿认证请求。

发起认证请求

接口名：InitFaceVerify

全局接入地址：cloudauth.aliyuncs.com（IPv4）或cloudauth-dualstack.aliyuncs.com（IPv6）

请求方法：POST和GET

传输协议：HTTPS

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

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

重要

金融级实人认证服务暂不支持基于调用次数的硬性封顶或自动停用功能。为有效控制成本并防范高额账单风险，建议在接入产品后及时配置消费告警规则：

  1. 配置消费预警：设置高额消费预警阈值，实时监控账单支出情况。

  2. 监控流量包余量：若已购买流量包，请同步设置资源包余量预警，以便及时补充资源或调整调用策略。

  3. 配置业务监控：参见告警通知设置，监控业务异动，及时识别业务请求波动。

请求参数

名称

类型

是否必选

描述

示例值

SceneId

Long

是

要接入的认证场景ID。该ID在控制台创建认证场景后自动生成。关于如何创建认证场景，请参见添加认证场景。

100000****

OuterOrderNo

String

是

您自定义的业务唯一标识，用于后续定位排查问题使用。

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

e0c34a77f5ac40a5aa5e6ed20c35****

ProductCode

String

是

要接入的认证方案。取值MFVC。

使用MFVC认证方案，您的用户需要进行活体认证和意愿表达。

MFVC

CertType

String

否

您的终端用户传入的证件类型。

当前仅支持身份证，取值固定为IDENTITY_CARD。

说明

在控制台进行意愿认证设置时，人脸对比源设置为权威数据源时，CertType为必填字段。

IDENTITY_CARD

CertName

String

否

您的终端用户的真实姓名。

说明

在控制台进行意愿认证设置时，人脸对比源设置为权威数据源时，CertName为必填字段。

王先生

CertNo

String

否

您的终端用户的证件号码。

说明

在控制台进行意愿认证设置时，人脸对比源设置为权威数据源时，CertNo为必填字段。

330103************

FaceContrastPicture

String

否

说明

在控制台进行意愿认证设置时，当人脸对比源设置为自定义比对源，您需要选择以下其中一种方式上传人脸照片：

  • FaceContrastPicture

  • FaceContrastPictureUrl

  • OSS

如果您选择OSS方式传入人脸照片，则必须传入OssBucketName和OssObjectName参数，格式仅支持开通实人认证服务时授权的OSS生成的URL、Bucket和Object。

照片Base64编码。

说明

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

/9j/4AAQSkZJRgABAQAASASBC****

FaceContrastPictureUrl

String

公网可访问的HTTP或HTTPS的人脸照片地址。

https://cn-shanghai-aliyun-cloudauth-****.oss-cn-shanghai.aliyuncs.com/verify/****.jpeg

OssBucketName

String

已授权OSS的存储空间（Bucket）名称。

cn-shanghai-aliyun-cloudauth-****

OssObjectName

String

已授权OSS存储空间的文件（Object）名称。

verify/****.jpeg

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

否

您的终端用户的手机号码。

130********

Ip

String

否

您的终端用户的IP。

114.100.XX.XX

UserId

String

否

您自定义的用户ID（最长100个字符），请保持唯一。

123456789

CallbackUrl

String

否

认证结果的回调通知地址，回调请求方式默认为GET，回调地址必须以https开头。平台在完成认证后会回调该地址，并自动添加certifyId、passed字段，passed字段值返回的是subcode值，示例：https://www.aliyun.com?callbackToken=1000004826&certifyId=shaxxxx&passed=200。

重要

  • 仅当认证完成（包含认证通过和认证未通过）时才会触发回调，若认证中放弃、异常中断或未进行认证均不会通知。建议您收到回调通知时，若有需要可通过查询接口获取认证详情信息。

  • 该值的传入会在调用接口前做可访问校验，如果传入的地址不能在公网访问，会返回401。

  • 接口在回调后务必返回 HTTP 状态码 200，否则会触发重试，3秒内两次回调。

https://www.aliyun.com

CallbackToken

String

否

安全Token，由您自行生成，用于防重复、防篡改校验。

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

NMjvQanQgplBSaEI0sL86******

AuthId

String

否

用户授权ID，最大长度为64位字符。

92d46b9e9e2d703f2897f350d5******

VoluntaryCustomizedContent

String

否

自定义意愿内容。 当开启个性化设置时必填。格式为String List的JSON String。

  • 跟读场景下：不能超过60个中文字符（不含标点），List只有1个元素。

  • 问答场景下：最多设置3个问题，每一个问题不能超过30个中文字符，每个问题分别为List的1个元素。

["本人王先生同意***协议。"]

needMultiFaceCheck

String

否

终端检测到多人脸时是否拦截，取值：

  • Y：拦截，客户端提示需要重新刷脸。

  • N（默认）：不拦截，取刷脸画面中的最大脸发送服务端进行安全检测。

Y

enableBeauty

String

否

是否启用刷脸时美颜效果。

  • Y：启用

  • N（默认）：不启用

重要

  • 仅当SDK完整集成该模块的版本时，该参数才能生效。

  • 启用美颜效果，不会影响留存人脸图片的质量。

  • 当前该功能仅支持安卓和iOS SDK。

N

返回数据

名称

类型

描述

示例值

RequestId

String

请求ID。

130A2C10-B9EE-4D84-88E3-5384FF039795

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的操作权限。具体操作，请参见授权RAM用户访问服务。

412

欠费中

金融级实人认证或OSS存在欠费，请充值后操作。

414

设备类型不支持

当前移动设备不支持刷脸认证，请更换设备后操作。

415

SDK版本不支持

当前认证SDK版本不支持刷脸认证，请升级SDK后操作。

416

系统版本不支持

当前操作系统版本不支持刷脸认证，请升级系统或更换设备操作。

417

无法使用刷脸服务

当前身份信息无可用比对源，导致此错误的原因请参考认证结果错误码ResultObject.SubCode）201、202和203的描述说明。更多内容，请参见DescribeFaceVerify-获取认证结果。

438

暂时无法使用声纹服务

已开启声纹对比功能，但未注册过声纹。请先进行声纹注册，具体操作，请参见设置意愿认证。

441

意愿内容错误

请传入意愿内容或在进行意愿设置时关闭自定义配置。

500

系统错误

系统内部错误，请反馈工程师排查。
上一篇：服务端接入下一篇：DescribeFaceVerify-获取认证结果