身份验证

更新时间：2020-12-22

人脸识别接口分为V2和V3两个版本，本文档为V2版本接口的说明文档，请确认您在百度云后台获得的是V2版本接口权限，再来阅读本文档。

辨别接口版本的方法是：在百度云后台进入【应用列表】，点击【应用名称】，在【API列表】中可以看到【请求地址】，若请求地址中带有【v2】标识，则您具有的是v2权限，可以阅读本文档；若请求地址中带有【v3】标识，则您具有的是v3权限，应该去阅读v3文档。如果您对文档内容有任何疑问，可以通过以下几种方式联系我们：

在百度云控制台内提交工单，咨询问题类型请选择人工智能服务；
如有需要讨论的疑问，欢迎进入 AI社区与其他开发者们一同交流。

能力介绍

业务能力

质量检测（可选）：判断图片中是否包含人脸，以及人脸在姿态、遮挡、模糊、光照等方面是否符合识别条件；
活体检测（可选）：基于图片中的破绽分析，判断其中的人脸是否为二次翻拍（举例：如用户A用手机拍摄了一张包含人脸的图片一，用户B翻拍了图片一得到了图片二，并用图片二伪造成用户A去进行识别操作，这种情况普遍发生在金融开户、实名认证等环节。）；
公安验证（必选）：基于姓名和身份证号，调取公民身份证小图（源自公安系统），将当前获取的人脸图片，与此证件小图进行对比，得出比对分数，并基于此进行业务判断是否为同一人。由于公安系统小图，具有最权威的身份证明作用，故对用户本人的验证结果可信度也最为合理。

业务逻辑

上述三项能力为顺序串行验证，接口默认返回公安身份对比分值，质量检测和活体检测为可选项。如选择了这两项，则验证顺序为人脸质量检测->活体检测->公安身份验证。您也可以根据业务场景，选择这两项中的某一项或都不选择。
如选择了前两个环节，则有任意一个条件不通过，则整个请求流程终止，并返回错误码，描述具体的不符合信息。
基于此顺序串行验证逻辑，可以避免大量不符合条件的请求流转到公安验证，节约您的成本。

推荐阈值

此接口使用的对比算法，针对带水纹证件照采用了专项的模型处理，可保证水纹信息的影响降到尽可能低。
如比对成功，最终返回的有效数据为一个对比分值，在0~1之间，您可以设定具体的阈值来判断是否验证通过。
人证相似度的推荐阈值为0.8，对应的误识率为万分之一。

计费逻辑

前两个环节图片不符合校验规则，会以error_code形式反馈，属于正向业务判断，这两个环节的请求全部免费。真正请求到公安验证这步并返回结果，才会进行计费。价格文档

调用方式

请求URL数据格式

向API服务地址使用POST发送请求，必须在URL中带上参数access_token，可通过后台的API Key和Secret Key生成，具体方式请参考“Access Token获取”。

获取access_token的示例代码

{% AccessToken %}

注意：access_token的有效期为30天，切记需要每30天进行定期更换，或者每次请求都拉取新token；

例如此接口，使用HTTPS POST发送：

https://aip.baidubce.com/rest/2.0/face/v2/person/verify?access_token=24.f9ba9c5341b67688ab4added8bc91dec.2592000.1485570332.282335-8574074

POST中Body的参数，按照下方请求参数说明选择即可。

提示：如果您为百度云老用户，正在使用其他非AI的服务，可以参考百度云AKSK鉴权方式发送请求，虽然请求方式和鉴权方法和本文所介绍的不同，但请求参数和返回结果一致。

请求说明

注意事项：

请求体格式化：Content-Type为application/x-www-form-urlencoded，通过urlencode格式化请求体。
Base64编码：请求的图片需经过Base64编码，图片的base64编码指将图片数据编码成一串字符串，使用该字符串代替图像地址。您可以首先得到图片的二进制，然后用Base64格式编码即可。需要注意的是，图片的base64编码是不包含图片头的，如data:image/jpg;base64,
图片格式：现支持PNG、JPG、JPEG、BMP，不支持GIF图片
人脸识别接口分为V2和V3两个版本，本文档为V2版本接口的说明文档，请确认您在百度云后台获得的是V2版本接口权限，再来阅读本文档。

辨别接口版本的方法是：在百度云后台进入【应用列表】，点击【应用名称】，在【API列表】中可以看到【请求地址】，若请求地址中带有【v2】标识，则您具有的是v2权限，可以阅读本文档；若请求地址中带有【v3】标识，则您具有的是v3权限，应该去阅读v3文档。

请求示例

HTTP方法：POST

请求URL： https://aip.baidubce.com/rest/2.0/face/v2/person/verify

URL参数：

参数	值
access_token	通过API Key和Secret Key获取的access_token,参考“Access Token获取”

Header：

参数	值
Content-Type	application/x-www-form-urlencoded

Body中放置请求参数，参数详情如下：

请求参数

参数	必选	类型	说明
image	是	string	*base64编码后的图片数据，需urlencode，编码后的图片大小不超过5M，图片尺寸不超过19201080**
id_card_number	是	uint32	身份证号（真实身份证号号码）。我们的服务端会做格式校验，并通过错误码返回，但是为了您的产品反馈体验更及时，建议在产品前端做一下号码格式校验与反馈
name	是	string	utf8，姓名（真实姓名，和身份证号匹配）
quality	否	string	判断图片中的人脸质量是否符合条件。`use`表示需要做质量控制，质量不符合条件的照片会被直接拒绝
quality_conf	否	string	人脸质量检测中每一项指标的具体阈值设定，json串形式，当指定`quality:use`时生效。默认使用的阈值如下： { `left_eye`：0.6，左眼被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `right_eye`：0.6，右眼被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `nose`：0.7，鼻子被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `mouth`：0.7，嘴巴被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `left_check`：0.8，左脸颊被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `right_check`：0.8，右脸颊被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `chin_contour`：0.6，下巴被遮挡的比例，取值范围[0~1]，数值越大遮挡越多； `illumination`：30，脸部光照的灰度值阈值，取值范围[0~255]，数值越大光照越强； `blurdegree`：0.7，人脸模糊度阈值，取值范围[0~1]，数值越大越模糊； }
faceliveness	否	sting	判断活体值是否达标。`use`表示需要做活体检测，低于活体阈值的照片会直接拒绝
faceliveness_conf	否	string	人脸活体检测的阈值设定，json串形式，当指定`faceliveness:use`时生效。默认使用的阈值如下： { `faceliveness：0.3`， //单帧图片活体检测阈值，取值范围[0~1]，大于阈值即可判断为活体 }
ext_fields	否	string	可选项为`faceliveness`，`qualities`。选择具体的项，则返回参数中将会显示相应的扩展字段。如`faceliveness`表示返回结果中包含活体相关内容，`qualities`表示返回结果中包含质量检测相关内容

返回说明

返回参数

参数	必须	类型	说明
log_id	是	uint64	日志id
result	是	float	与公安小图相似度可能性，用于验证生活照与公安小图是否为同一人，有正常分数时为[0~1]，推荐阈值0.8，超过即判断为同一人
ext_info	否	string	拓展信息json串，只有选择了`ext_fields`时才会返回具体信息。选择`faceliveness`返回具体活体分值信息，选择`qualities`返回人脸质量检测信息。两者可以同时选择，半角逗号分割。
+faceliveness	否	string	活体检测值，单帧图片建议阈值，小于此值则认为不是活体，超过则判断为活体
+qualities	否	string	质量检测结果
++occlusion	否	string	人脸遮挡情况
+++left_eye	否	string	左眼被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.6
+++right_eye	否	string	右眼被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.6
+++nose	否	string	鼻子被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.7
+++mouth	否	string	嘴巴被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.7
+++left_cheek	否	string	左脸颊被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.8
+++right_cheek	否	string	右脸颊被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.8
+++chin	否	string	下巴被遮挡的比例，取值范围[0~1]，数值越大遮挡越多；小于阈值时有返回，默认阈值0.8
++blur	否	string	人脸模糊度阈值，取值范围[0~1]，数值越大越模糊；小于阈值时有返回，默认阈值0.7
++illumination	否	string	脸部光照的灰度值阈值，取值范围[0~255]，数值越大光照越强；大于阈值时有返回，默认阈值30
++completeness	否	string	人脸完整度，0或1, 0为人脸溢出图像边界，1为人脸都在图像边界内

返回示例

{
   "result":0.03419, 
   "ext_info":{
      "faceliveness":0.47 
   },
   "log_id":772889134072410 
 }

错误码

请参考人脸识别错误码

人脸库管理

在线活体检测