接口文档
H5人脸实名认证方案提供多接口能力,实现以下功能:
- 对比图片上传:上传用于1:1人脸比对的人脸底图,快速直达
- 指定用户信息上报:上传用于权威数据源验证时的用户身份证号码、姓名,实现无需用户拍照或手动输入,直接进行活体及识别,快速直达
- 获取认证人脸:获取认证成功最终采集的人脸信息,快速直达
- 查询认证结果:获取身份证信息(仅在使用OCR的情况下返回)、活体检测分数、人脸相似度得分,快速直达
- 实时方案视频获取:获取实时活体检测过程的视频/图片,快速直达
H5人脸实名认证方案的配套功能:
- 记录查询:如您希望获取方案的记录信息,可开通记录查询功能进行可视化查看。
- 数据报警:通过简单设置,即可对接口的安全风险监控,为业务保驾护航。当后台监测到接口受到攻击,或其他异常情况时,将向指定的邮箱发送报警邮件,提示及时处理问题,开通数据报警功能进行可视化查看。
一、方案功能接口
1.获取verify_token接口
本接口为H5实名认证方案的verify_token获取接口,利用所获取的verify_token进行实名认证流程的有效期为2小时。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/verifyToken/generate
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
请求参数:
参数 | 必选 | 类型 | 说明 |
---|---|---|---|
plan_id | 是 | string | 方案的id信息,请在人脸实名认证控制台查看创建的H5方案的方案ID信息 |
请求示例:
{
"plan_id" : 1
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
result | 是 | array | 请求结果 |
+verify_token | 是 | string | 请求获取的verify_token |
-
返回示例
{ "success": true, "result": { "verify_token": "Yz9rWITm4vak16PBAh5x8oG7" }, "log_id": "1814798895" }
2.指定用户信息上报接口
本接口用于,前端在方案中选择身份信息录入-身份信息录入方式-指定用户身份核验时,需要先调用此接口输入指定用户的姓名+身份证号信息,再请求url跳转页面。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL:https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/idcard/submit
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
参数 | 必选 | 类型 | 值 |
---|---|---|---|
verify_token | 是 | string | 通过access_token获取的verify_token |
id_name | 是 | string | 指定输入用户的姓名信息 |
id_no | 是 | string | 指定输入用户的身份证件号信息 |
certificate_type | 否 | Int | 证件类型: 0 大陆居民二代身份证 1 港澳台居民来往内地通行证 2 外国人永久居留证 3 定居国外的中国公民护照 4 港澳台居民居住证 |
请求示例:
{
"verify_token": "2sF3nE5mXOHkx2aQwWG4n5WI",
"id_name": "张三",
"id_no": "500***********3390",
"certificate_type": 0 // 证件类型:0:大陆居民二代身份证,1:港澳台居民来往内地通行证,2:外国人永久居留证,3:定居国外的中国公民护照,4:港澳台居民居住证
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
result | 是 | array | 请求结果,返回固定结果1,可忽略 |
-
返回示例
{ "success": true, "result": 1, "log_id": "1244068892" }
3.对比图片上传接口
本接口用于,前端在方案中选择比对源选择-自建人脸库比对时,需要先调用此接口上传待比对的自建人脸库中的指定人脸图片,再请求url跳转页面。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/uploadMatchImage
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
参数 | 必选 | 类型 | 值 |
---|---|---|---|
verify_token | 是 | string | 通过access_token获取的verify_token |
image | 是 | string | 图片base64字符串,编码后的图片大小不超过10M,图片分辨率小于1920*1080 |
quality_control | 否 | string | “NONE”、“LOW”、“NORMAL”、“HIGH”;质量控制参数,未主动传入时默认为“NONE” |
liveness_control | 否 | string | “NONE”、“LOW”、“NORMAL”、“HIGH”;活体控制参数,未主动传入时默认为“NONE” |
请求示例:
{
"verify_token": "2sF3nE5mXOHkx2aQwWG4n5WI",
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD/",
"quality_control" : "LOW",
"liveness_control" : "LOW",
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
log_id | 是 | string | logid |
result | 是 | array | 返回结果 |
-
返回示例
{ "success": true, "result": null, "log_id": "1329130892" }
二、验证后查询接口
获取Token后,请先按照跳转实名认证H5 URL,用户进行操作后再查询接口,否则生成Token无法生效。
1.获取认证人脸接口
本接口返回进行人脸实名认证过程中进行认证的最终采集的人脸信息(仅在认证成功时返回人脸信息,认证失败返回错误码)。根据Verify_token返回的结果信息会在云端保留3天,您可根据需要在此期间进行调取查询。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/simple
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
参数 | 值 |
---|---|
verify_token | 通过access_token获取的verify_token |
请求示例:
{
"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
result | 是 | array | 请求结果 |
+image | 是 | string | 返回采集的用户人脸信息 (仅在认证成功时返回人脸信息,认证失败返回错误码) |
-
返回示例
{ "success": true, "result": { "image":"https://brain.baidu.com/solution/faceprint/image/query?verify_token=xxxxxx" }, "log_id": "1054986003" }
2.查询认证结果接口
本接口为请求返回的认证结果信息查询,包含身份证OCR识别信息、用户二次确认的身份证信息,活体检测信息、及用户对权威数据源图片进行比对的分数信息。(仅在认证成功时返回上述信息,认证失败返回错误码)根据Verify_token返回的结果信息会在云端保留3天,您可根据需要在此期间进行调取查询。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/detail
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
参数 | 值 |
---|---|
verify_token | 通过access_token获取的verify_token |
请求示例:
{
"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
result | 是 | array | 请求结果 |
+idcard_ocr_result | 否 | array | 返回采集的身份证信息 当人脸实名认证控制台设置为使用OCR识别时返回此参数信息 |
++address | 否 | string | 地址 |
++birthday | 否 | string | 生日 |
++name | 否 | string | 姓名 |
++id_card_number | 否 | string | 身份证号 |
++gender | 否 | string | 性别 |
++nation | 否 | string | 民族 |
++expire_time | 否 | string | 身份证失效日期 |
++issue_authority | 否 | string | 身份证签发机关 |
++issue_time | 否 | string | 身份证生效日期 |
+idcard_images | 否 | array | 返回采集的身份证图片信息 当人脸实名认证控制台设置为使用OCR识别时返回此参数信息 |
++front_base64 | 否 | string | 身份证图片的正面信息 |
++back_base64 | 否 | string | 身份证图片的反面信息 当人脸实名认证控制台设置为使用OCR识别且为国徽面+人像面时返回此参数信息 |
+verify_result | 是 | array | 认证返还信息 |
++liveness_score | 是 | string | 活体检测分数: 在线图片/动作活体:活体验证通过时返回活体分数,不通过则返回0。 炫瞳活体:活体通过/不通过均会返回0 |
++score | 是 | string | 人脸实名认证 |
++spoofing | 是 | string | 合成图分数 若未进行合成图检测,则返回0 若进行活体检测,则返回合成图检测分值 |
is_demote | 否 | bool | 当配置为实时活体检测方案时是否降级,true为降级,false为不降级 |
+idcard_confirm | 是 | array | 用户二次确认的身份证信息 |
++name | 是 | string | 姓名 |
++idcard_number | 是 | string | 身份证号 |
-
返回示例
{ "success": true, "result": { "verify_result": { "score": 93.7835, "liveness_score": 0.9672966, "spoofing": 0.0 }, "idcard_ocr_result": { "birthday": "19960216", "issue_authority": "胶南市公安局", "address": "山东省***********", "gender": "女", "nation": "汉", "expire_time": "20221103", "name": "柴*", "issue_time": "20121103", "id_card_number": "370***********5826" }, "idcard_images": { "front_base64": "/9j/4AAQSkZJRgAB....", "back_base64": "/9j/4AAQSkZJRgAB...." }, "idcard_confirm": { "idcard_number": "370***********5826", "name": "柴*" } }, "log_id": "160931948204246" }
3.查询统计结果
根据Verify_token返回的结果信息会在云端保留3天,您可根据需要在此期间进行调取查询。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/stat
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
参数 | 值 |
---|---|
verify_token | 通过access_token获取的verify_token |
请求示例:
{
"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
result | 是 | array | 请求结果 |
+Verify_FIN | 是 | array | 人脸实名认证接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | int | 当前错误码的请求数量 |
+Sessioncode | 是 | array | 随机校验码接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | int | 当前错误码的请求数量 |
+OCR | 是 | array | OCR身份证识别接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | int | 当前错误码的请求数量 |
+verify | 是 | array | 人脸实名认证接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | int | 当前错误码的请求数量 |
+VideoLiveness | 是 | array | 视频活体检测接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | string | 当前错误码的请求数量 |
+Livenesscolorful | 是 | array | 炫瞳活体检测接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | string | 当前错误码的请求数量 |
+VerifySec | 是 | array | 人脸实名认证接口请求的统计信息 |
++error_code | 是 | string | 错误码编号 若为0则表示请求成功 |
++count | 是 | string | 当前错误码的请求数量 |
-
返回示例
{ "success": true, "result": { "Verify_FIN": [ { "error_code": 0, "count": 1 } ], "Sessioncode": [ { "error_code": 0, "count": 1 } ], "OCR": [ { "error_code": 0, "count": 2 } ], "verify": [ { "error_code": 0, "count": 1 } ], "VideoLiveness": [ { "error_code": 0, "count": 1 } ] "Livenesscolorful": [ { "error_code": 0, "count": 1 } ] "VerifySec": [ { "error_code": 0, "count": 1 } ] }, "log_id": "1405335905" }
4.实时方案视频获取
根据Verify_token返回的视频url会在云端保留1天,您可根据需要在此期间进行调取查询。
注意:H5方案中的视频录制功能默认不开启,调用本接口将无法获得视频数据,如您需要使用以上api,请联系商务经理或提交工单申请配置开通
调用方式
请求URL数据格式
向API服务地址使用POST发送请求,必须在URL中带上参数access_token
,可通过后台的API Key和Secret Key生成,具体方式请参考“Access Token获取”。
注意:
access_token
的有效期为30天,切记需要每30天进行定期更换,或者每次请求都拉取新token;
POST中Body的参数,按照下方请求参数说明选择即可。
提示:如果您为百度云老用户,正在使用其他非AI的服务,可以参考百度云AKSK鉴权方式发送请求,虽然请求方式和鉴权方法和本文所介绍的不同,但请求参数和返回结果一致。
在线调试
您可以在 示例代码中心 中调试该接口,可进行签名验证、查看在线调用的请求内容和返回结果、示例代码的自动生成。
请求说明
注意事项:
- 请求体格式化:Content-Type为
application/json
,通过json
格式化请求体。
请求示例
HTTP方法:POST
请求URL: https://aip.baidubce.com/rpc/2.0/brain/solution/faceprint/result/media/query
URL参数:
参数 | 值 |
---|---|
access_token | 通过API Key和Secret Key获取的access_token,参考“Access Token获取” |
Header:
参数 | 值 |
---|---|
Content-Type | application/json |
Body中放置请求参数,参数详情如下:
参数 | 值 |
---|---|
verify_token | 通过access_token获取的verify_token |
请求示例:
{
"verify_token" : "cIupeyP51sn28XzxGVTfYqoN"
}
返回参数
- 返回结果
字段 | 必选 | 类型 | 说明 |
---|---|---|---|
success | 是 | boolean | 返回请求是否成功信息。 若请求成功返回ture; 请求失败则返回false |
result | 是 | string | 视频url链接 |
+processVideo | 是 | string[] | H5实时炫瞳活体、H5实时动作活体、H5实时静默活体方案视频链接数组,一个verify_token仅对应一个视频 |
+video | 是 | string[] | H5数字活体、H5动作活体、H5视频活体、在线图片活体方案视频链接数组,一个verify_token仅对应一个视频,video和processVideo不会同时返回 |
+images | 是 | string[] | 图片链接数组,H5实时炫瞳活体、H5实时动作活体、H5实时静默活体方案所返回的4张人脸图片 |
+extInfo | 是 | string | 扩展信息,如有则代表处理视频中的错误信息 |
log_id | 是 | string | 日志ID |
- 返回示例
{
"success": true,
"result": {
"processVideo": [
"http://bj.bcebos.com/v1/aa.mp4"
],
"video": [
"http://bj.bcebos.com/v1/aa.mp4"
],
"images": [
"http://bj.bcebos.com/v1/aa.jpg"
],
"extInfo": null
},
"log_id": "1534116864874049322"
}
三、常见问题
1. verify_token的详细说明
(1)access_token 有效期为 30 天,重复生成 access_token 的话,对之前的不影响,依旧能使用;access_token 与verify_token 是包含关系,即 verify_token 是由 access_token生成的,如果一个 verify_token 是和一个不匹配的 access_token 使用,会提示“Token无效或者已过期”
(2)verify_token 的核验有效期为 2 小时,在有效期内可以进行了核验动作,如果超过了 2 小时没有使用该 token 进行核验的话会提示“Token无效或者已过期”
(3) verify_token 核验完毕后(核验成功,或设置了认证未通过时URL失效),无法再进行核验,如果再次进行核验,会提示“Token无效或者已过期”
(4) verify_token 核验完毕后(核验成功,或设置了认证未通过时URL失效),支持对后验接口的查询,有效期均为 3 天,3 天后再次查询后验接口,会提示“Token无效或者已过期”