调用VerifyMaterial，在纯服务端接入的认证方案中，传入姓名、身份证号、人像照、身份证正反面照片（可选）进行实人认证，并同步返回认证结果。

接入准备：接入该API时，请确保已经完成相应的准备工作。更多内容，请参见实人认证方案接入流程概述。

请求方法：HTTPS POST和GET。

接口描述：接入方服务端提交认证材料到实人认证服务进行核实比对，结果同步返回。

适用范围：该接口仅适用于纯服务端接入的认证方案。

上传图片地址说明：

  • HTTP或HTTPS地址：支持公网可访问的HTTP或HTTPS地址。例如，http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg。
  • 本地文件：传入本地图片时，可以使用图片的相对路径或绝对路径。

图片限制说明：

  • 单张图片大小请控制在2 MB内，避免算法拉取超时。
  • 图片中人脸区域的大小至少64*64像素。

本文是最新版的接口文档，如果您需要查看之前版本，请参见VerifyMaterial。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 VerifyMaterial

要执行的操作。取值：VerifyMaterial。
BizId String 是 39ecf51e-2f81-4dc5-90ee-ff86125b****

标识一次认证任务的唯一ID，不超过64字符。针对一次认证任务，系统支持无限次发起提交，直到最终认证通过，该任务完结。

说明 发起不同的认证任务时需要更换不同的BizId。
BizType String 是 RPMinTest

使用实人认证服务的业务场景标识。请先参见业务设置在控制台完成创建。
FaceImageUrl String 是 http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg

人像正面照图片的HTTP或HTTPS链接。
IdCardFrontImageUrl String 是 http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg

身份证人像面图片的HTTP或HTTPS链接。
IdCardNumber String 是 02343218901123****

身份证号。
Name String 是 张三

姓名。
IdCardBackImageUrl String 否 http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg

身份证国徽面图片的HTTP或HTTPS链接。
UserId String 否 54sdj

终端用户的ID，例如终端用户的账号ID。
RegionId String 否 ch-hangzhou

地域。

返回数据

名称 类型 示例值 描述
Code String 200

HTTP状态码。
Message String success

请求参数的响应信息。
RequestId String 04F0F334-1335-436C-A1D7-6C044FE73368

本次请求的ID。
ResultObject Struct

结果信息。
AuthorityComparisionScore Float 97

认证过程中所提交的人脸照片和权威数据的比对分，取值范围：0~100。

置信度阈值请参考：

  • 误识率0.001%时，对应阈值95。
  • 误识率0.01%时，对应阈值90。
  • 误识率为0.1%时，对应阈值80。
  • 误识率为1%时，对应阈值为60。
说明 该字段只表示人脸与权威数据的比对结果，是个参考分，通常不建议业务上仅以该分数作为是否通过的标准。认证的综合结果请参考VerifyStatus字段。VerifyStatus的结果综合了人脸与权威数据的比对和其他多种策略，可以提高安全水位。
IdCardFaceComparisonScore Float 97

认证过程中所提交的人脸照片和身份证人像面图片上人脸的比对分，取值范围：0~100。

置信度阈值请参考：

  • 误识率0.001%时，对应阈值95。
  • 误识率0.01%时，对应阈值90。
  • 误识率为0.1%时，对应阈值80。
  • 误识率为1%时，对应阈值为60。
Material Struct

认证材料。
FaceGlobalUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/face-global-example.jpg

实人认证SDK采集到的摄像头全局图。

说明 该参数需要配置后才会生效。
FaceImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg

人像正面照图片的HTTP或HTTPS链接，对应于请求参数FaceImageUrl。链接地址5分钟内有效，建议业务上进行转存以免影响使用。
FaceMask String false

人脸是否佩戴口罩。取值：

  • true：佩戴了口罩
  • false：未佩戴口罩
FaceQuality String NORMAL

人脸正面照图片的质量。取值：

  • UNQUALIFIED：照片质量较差
  • LOW：低
  • NORMAL：一般
  • HIGH：高
IdCardInfo Struct

身份证信息的OCR结果。

说明 认证过程中如果没有身份证正面和身份证反面，则不会返回身份证信息的OCR结果。认证过程中如果有身份证正面和身份证反面，也不保证一定会返回身份证上所有的信息，因身份证拍摄问题等引起的OCR无法识别时，OCR信息就会不全，建议接入方业务上不强依赖身份证OCR信息。
Address String 浙江省杭州市余杭区文一西路969号

地址。
Authority String 杭州市公安局

签发机构。
BackImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg

身份证国徽面图片的HTTP或HTTPS链接。链接地址5分钟内有效，建议业务上进行转存以免影响使用。
Birth String 19900101

出生日期。
EndDate String 20201101

证件有效期结束时间。格式为：yyyymmdd。
FrontImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg

身份证人像面图片的HTTP或HTTPS链接。链接地址5分钟内有效，建议业务上进行转存以免影响使用。
Name String 张三

姓名。
Nationality String 汉

民族。
Number String 02343218901123****

身份证号。
StartDate String 20201101

证件有效期开始时间。格式为：yyyymmdd。
IdCardName String 张三

姓名，对应于请求参数Name。
IdCardNumber String 02343218901123****

身份证号，对应于请求参数IdCardNumber。
VerifyStatus Integer 1

认证状态。取值：

  • 1：认证通过。
  • 2~n：由于不同原因导致认证不通过。详细描述请参见下文的认证状态说明。
VerifyToken String c302c0797679457685410ee51a5ba375

该次认证的Token，用来串联认证请求中的各个接口，在30分钟内有效。
Success Boolean true

是否成功响应。

  • true：响应成功。
  • false：响应失败。

认证状态说明

VerifyStatus

原因说明

1

认证通过。

2

认证不通过，原因：实名校验不通过。

3

认证不通过，可能原因：身份证照片模糊、光线问题造成字体无法识别、身份证照片信息与需认证的身份证姓名不一致、提交的照片为非身份证照片。

4

认证不通过，可能原因：身份证照片模糊、光线问题造成字体无法识别、身份证照片信息与需认证的身份证号码不一致、提交的照片为非身份证照片。

5

认证不通过，可能原因：身份证照片上的有效期已过期（或即将过期）。

6

认证不通过，可能原因：人脸与身份证头像不一致。

7

认证不通过，可能原因：人脸与公安网照片不一致。

8

认证不通过，可能原因：提交的身份证照片非身份证原照片、未提交有效身份证照片。

9

认证不通过，可能原因：非账户本人操作。

11

认证不通过，可能原因：公安网照片缺失、公安网照片格式错误、公安网照片未找到人脸。

12

认证不通过，可能原因：公安网系统异常，无法进行照片比对等可能。

示例

请求示例

http(s)://[Endpoint]/?Action=VerifyMaterial
&BizId=39ecf51e-2f81-4dc5-90ee-ff86125b****
&BizType=RPMinTest
&FaceImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
&IdCardFrontImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg
&IdCardNumber=02343218901123****
&Name=张三
&<公共请求参数>

正常返回示例

XML格式

<VerifyMaterialResponse>
	  <ResultObject>
		    <VerifyStatus>1</VerifyStatus>
		    <AuthorityComparisionScore>97</AuthorityComparisionScore>
		    <VerifyToken>c302c0797679457685410ee51a5ba375</VerifyToken>
		    <IdCardFaceComparisonScore>97</IdCardFaceComparisonScore>
		    <Material>
			      <FaceGlobalUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/face-global-example.jpg</FaceGlobalUrl>
			      <IdCardName>张三</IdCardName>
			      <FaceQuality>NORMAL</FaceQuality>
			      <IdCardNumber>02343218901123****</IdCardNumber>
			      <FaceMask>false</FaceMask>
			      <FaceImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg</FaceImageUrl>
			      <IdCardInfo>
				        <StartDate>20201101</StartDate>
				        <Address>浙江省杭州市余杭区文一西路969号</Address>
				        <Number>02343218901123****</Number>
				        <Authority>杭州市公安局</Authority>
				        <Sex></Sex>
				        <BackImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg</BackImageUrl>
				        <FrontImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg</FrontImageUrl>
				        <Birth>19900101</Birth>
				        <EndDate>20201101</EndDate>
				        <Nationality>汉</Nationality>
				        <Name>张三</Name>
			      </IdCardInfo>
		    </Material>
	  </ResultObject>
	  <Message>success</Message>
	  <RequestId>04F0F334-1335-436C-A1D7-6C044FE73368</RequestId>
	  <Code>200</Code>
  </VerifyMaterialResponse>

JSON格式

{"ResultObject":{"VerifyStatus":"1","AuthorityComparisionScore":"97","VerifyToken":"c302c0797679457685410ee51a5ba375","IdCardFaceComparisonScore":"97","Material":{"FaceGlobalUrl":"http://image-demo.img-cn-hangzhou.aliyuncs.com/face-global-example.jpg","IdCardName":"张三","FaceQuality":"NORMAL","IdCardNumber":"02343218901123****","FaceMask":"false","FaceImageUrl":"http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg","IdCardInfo":{"StartDate":"20201101","Address":"浙江省杭州市余杭区文一西路969号","Number":"02343218901123****","Authority":"杭州市公安局","BackImageUrl":"http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg","FrontImageUrl":"http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg","Birth":"19900101","EndDate":"20201101","Nationality":"汉","Name":"张三"}}},"Message":"success","RequestId":"04F0F334-1335-436C-A1D7-6C044FE73368","Code":"200","Success":"true"}

错误码

HttpCode 错误码 错误信息 描述
400 ParameterIsNull The parameter must not be empty. 参数不能为空。
401 InvalidParameter The specified parameter is invalid. 非法参数。
403 NoPermission This RAM user has no permissions to access API. 该RAM用户无权访问API。
410 NoSubscribeService OSS is not activated or you have not granted OSS the read write permission. 未开通OSS产品或未完成OSS读写授权，请登录控制台完成授权。
412 InDebt You have an outstanding payment. Please add funds first and try again. 实人认证存在欠费，请充值后再进行操作。
421 ResourcesTooLarge The size of the incoming resources are too large. 传入资源超过了最大限制。
422 DownloadTimedOut Downloading resource timed out. 下载资源超时（3秒）。
435 NoFaceDetected No face is detected in either the image or the video. 图片或者视频中检测不到人脸信息。
500 SystemError A system error occurred. 系统内部错误。

访问错误中心查看更多错误码。