接入文档
FaceID增强版
APP接入
API接口
比对认证
比对认证
# 版本
5.0.0
# 描述
此接口用于将FaceID MegLiveStill SDK 所获得的数据进行上传,并获取活体验证、人脸比对、攻击防范等结果信息。
# 调用URL
https://api.megvii.com/faceid/v5/sdk/verify
注意:在生产环境中,请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路,存在安全风险,请勿在生产环境中使用。在生产环境中使用HTTP方式的,将无法得到服务可靠性保障。
# 调用方法
POST 注意:用 form-data 格式请求
# 权限
仅当用户接入FaceID产品后,才能调用FaceID各Web API。接入FaceID的流程请咨询FaceID商务人员。
# 参数
必选/可选 | 参数 | 类型 | 参数说明 | ||
必选 | sign | String | 调用此API客户的签名,具体的签名产生方式请查阅App-鉴权说明 | ||
必选 | sign_version | String | 签名算法版本号,请传递:hmac_sha1 | ||
可选 | biz_no | String | “默认为空”。客户业务流水号,建议设置为您的业务相关的流水串号并且唯一,会在return时原封不动的返回给您的服务器,以帮助您确认对应业务的归属。此字段不超过128字节 | ||
必选 | comparison_type | String |
本次请求的验证方式 |
||
必选 | data_type | String |
验证数据来源 |
||
必选 | verify_id | String | verify场景id:本次验证请求相关配置在控台可设置,并将生成的id号在接口中使用 | ||
必选 | encryption_type | String |
是否开启传输数据加密,详细说明见:加密说明 |
||
待验证数据传入 | data_type=0 | 条件必选 | biz_token | String | get_biz_token接口获取的biz_token;用以标识本次核验数据对象 |
data_type=1 | 条件必选 | image | File | 通过传入自有照片进行验证,需传输 | |
可选 | biz_token | String | get_biz_token接口获取的biz_token,用以串联业务请求 | ||
参考数据传入 | comparison_type=1(人身核验) | 条件必选 | idcard_name | String | 需要核实对象的姓名,使用UTF-8编码 |
条件必选 | idcard_number | String | 需要核实对象的证件号码,也就是一个18位长度的字符串 | ||
可选 | image_ref1 | File | 由应用方提供的参照人脸照片。如果在image_ref1中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对 | ||
comparison_type=0(人脸比对) | 条件必选 | uuid | String | 如果应用方不使用参考数据进行比对,则上传此字段,用于标志本次识别对应的用户的唯一ID,要求不长于128字节。建议您对来自同一用户的比对请求使用同样的ID,这非常有利于您反查验证结果以及获得更好的数据报表体验 | |
条件必选 | image_ref1 | File | 由应用方提供的参照人脸照片。如果在image_ref1、image_ref2中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对 | ||
可选 | image_ref2 | File | 由应用方提供的参照人脸照片。如果在image_ref1、image_ref2中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对 | ||
comparison_type=2(实证核身) | 可选 | image_ref1 | File | 由应用方提供的参照人脸照片。如果在image_ref1中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对 |
# 返回值说明
参数类别 | 参数 | 类型 | 参数说明 | ||||||||||||||||||||||||||||||
#基础返回信息 | request_id | String | API 调用的流水号 | ||||||||||||||||||||||||||||||
biz_no | String | 传入的业务流水号,原封不动地返回 | |||||||||||||||||||||||||||||||
time_used | Int | 整个请求所花费的时间,单位为毫秒。此字段必定返回 | |||||||||||||||||||||||||||||||
user_faced_time | String | 用户刷脸发生的时间 | |||||||||||||||||||||||||||||||
error | String | 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节,否则此字段不存在 | |||||||||||||||||||||||||||||||
#状态码 | result_code | Int |
表示本次验证的结果状态码。可结合result_code和result_message字段知晓具体的结果及原因:
|
||||||||||||||||||||||||||||||
#状态码描述 | result_message | String | 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表 | ||||||||||||||||||||||||||||||
#比对结果 | verification | Json |
|
||||||||||||||||||||||||||||||
#攻击结果 | attack_result | Json |
|
||||||||||||||||||||||||||||||
#设备攻击信息描述 | device_risk_info | Json |
设备风险检测结果:
|
||||||||||||||||||||||||||||||
#附加返回信息 | images | Json |
一组照片列表,后续会根据采集的照片增加对应的照片字段
|
||||||||||||||||||||||||||||||
video_key | String | 解密密钥,用于获取SDK端保存的视频及图片 | |||||||||||||||||||||||||||||||
face | Json |
当选用image方式时返回待验证图片image的属性:
|
|||||||||||||||||||||||||||||||
visual_attributes | Json |
附加属性:
|
|||||||||||||||||||||||||||||||
verify_risk_info | Json |
比对风险提示结果:
|
# 返回值示例
正确请求返回示例
{
"request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
"biz_no":"",
"time_used":1448,
"user_faced_time":2021-12-21 10:11:11,
"result_code":1000,
"result_message":"SUCCESS",
"verification":{
"idcard":{
"confidence":86.63057,
"thresholds":{
"1e-3":62.168713,
"1e-5":74.39926,
"1e-4":69.31534,
"1e-6":78.038055
}
}
},
"attack_result":{
"score":0.26,
"threshold":0.5,
"result":False
},
"device_risk_info":{
"device_info_level": "2",
"device_info_tags": {"is_root":0,"is_hook":1,"is_injection":1,"is_virtual_environment":1,"is_other_risks":1}
},
"images":{
"image_best":"xxxxxxxxxxx"
},
"video_key":"asdffff"
"face":{
"quality":38.221,
"quality_threshold":30.1,
"rect":{
"left":0.18,
"top":0.18,
"width":0.596,
"height":0.596
},
"orientation":90
}
}
失败请求返回示例
{
"error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}
# result_code & result_message 对照表
result_code | result_message | 含义解释 | 是否计费 |
---|---|---|---|
1000 | SUCCESS | 验证成功 | 是,详细计费请咨询商务 |
2000 | PASS_LIVING_NOT_THE_SAME | 通过了活体检测,但是经过验证,待比对照片与其他照片中的至少一张,不是同一个人 | 是 |
3000 | NO_ID_CARD_NUMBER | 无此身份证号 | 是 |
3000 | ID_NUMBER_NAME_NOT_MATCH | 证件号码和姓名不匹配 | 是 |
3000 | NO_FACE_FOUND | 姓名和身份证号码正确,但照片没有检测到人脸 | 是 |
3000 | NO_ID_PHOTO | 找不到参考照片 | 是 |
3000 | PHOTO_FORMAT_ERROR | 参考照片格式错误 | 是 |
3000 | DATA_SOURCE_ERROR | 参考数据出现错误 | 否 |
4100 | FAIL_LIVING_FACE_ATTACK | 未经过活体判断,可能的原因:是假脸攻击 | 是 |
4100 | VIDEO_LACK_FRAMES | 获取到的活体数据故障,请换一台手机重试 | 否 |
4200 | BIZ_TOKEN_DENIED | 传入的 biz_token 不符合要求 | 否 |
4200 | AUTHENTICATION_FAIL | 鉴权失败 | 否 |
4200 | MOBILE_PHONE_NOT_SUPPORT | 手机不在支持列表里 | 否 |
4200 | SDK_TOO_OLD | SDK版本过旧,已经不被支持 | 否 |
4200 | MOBILE_PHONE_NO_AUTHORITY | 没有权限(运动传感器、存储、相机) | 否 |
4300 | NO_FOUND_EID_REF | 实证核身没有找到数据源,原因可能如下:没有调用NFC查询后仍然调用人脸比对服务 | 否 |
# 错误码列表
HTTP状态代码 | 错误信息 | 说明 |
---|---|---|
400 | MISSING_ARGUMENTS:<key> | 缺少某个必选参数 |
400 | BAD_ARGUMENTS:<key> |
某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长)
注意:<meglive_data>错误代表当前token没有调用SDK,缺少活体数据报错 |
400 | IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> | 参数<param>对应的图像无法解析,有可能不是图像文件、或有数据破损。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称 |
400 | NO_FACE_FOUND:<param> | 表示上传的 image_ref 的图像中,没有检测到人脸。<param>为 image_ref1、 image_ref2、image中的一个。请注意:<param>只会有一项,即第一个满足条件的名称 |
400 | INVALID_IMAGE_SIZE:<param> | 客户上传的图像太大,具体是指像素尺寸的长或宽超过4096像素。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称 |
400 | LOW_QUALITY | image图片质量太差 |
400 | MULTIPLE_FACES | image图片中有多张人脸 |
400 | MEGLIVE_DATA_ERROR | 上传的活体数据解析失败。请将SDK产生的meglive_data数据包直接传递到此API,任何对数据包的修改都会导致数据包解析失败的问题 |
400 | DATA_APPKEY_NOT_MATCH | 上传的meglive_data包中的key/token与对应key不一致 |
400 | KEY_NOT_FOUND | encryption_type开启加密,但未配置加密公钥和解密私钥 |
400 | FMP_CONTENT_TYPE_ERROR | 视频错误,请重试或更换手机重试 |
403 | AUTHENTICATION_ERROR | 无效签名 |
403 | AUTHORIZATION_ERROR:<reason> |
api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限 <reason>取值:
|
403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
404 | API_NOT_FOUND | 所调用的API不存在 |
413 | Request Entity Too Large | 客户发送的请求大小超过了10MB限制或单张照片大小超过了2MB。该错误的返回格式为纯文本,不是json格式 |
500 | INTERNAL_ERROR | 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务 |
该文档未解决您的疑问?查看常见问题