接入文档
FaceID基础版
H5接入
API调用
获取比对结果
获取比对结果
# 调用URL
GET https://api.megvii.com/faceid/lite/get_result
注意：在生产环境中，请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路，存在安全风险，请勿在生产环境中使用。在生产环境中使用HTTP方式的，将无法得到服务可靠性保障。
说明：此接口提供活体结果反查功能，可以以biz_id为索引对 FaceID H5验证结果进行反查。该接口的调用信息保存有效期为一天，且仅支持3次调用。第4次或超过有效期调用则会返回错误信息，建议在每笔业务结束之后及时的取回数据。
# 参数
| 必选／可选 | 参数 | 类型 | 参数说明 |
|---|---|---|---|
| 必选 | api_key | String | 调用此API的api_key |
| 必选 | api_secret | String | 调用此API的api_key的secret |
| 必选 | biz_id | String | 通过get_token, notify_url或者return_url返回的活体业务编号 |
| 可选 | return_verify_time | String | 该参数用于控制验证发生时间信息的返回 0（默认）：不返回做验证发生的时间 1：需要返回验证发生的时间 |
| 可选 | return_image | String |
此参数为可选参数，可在下面三种参数中选择，决定了是否返回活体图像数据：
|
# 返回值说明
| 参数 | 类型 | 说明 | 示例 |
|---|---|---|---|
| request_id | String | API 调用的流水号 |
"1462259763, e2d2f8d6-204b-4c43 -92ea-1d62b071f83c" |
| status | String |
此字段仅表示当前FaceID H5验证流程是否正常结束，非人脸核验结果。活体检测结果查看liveness_result字段，人脸比对结果查看verify_result字段。
|
"OK" |
| fail_reason | String |
status为“WEBRTC_UNSUPPORTED”的具体失败原因,当“get_fail_reason”=1时返回
|
“NETWORK_ERROR” |
| biz_info | Json |
包含：biz_id, biz_no, biz_extra_data
|
{
"biz_extra_data": "...", "biz_id": "1462259748, 52b13fb5-8dfb-4537 -a62b-a641d5e929f1", "biz_no": "cc47190f-5502-44a2 -ab74-ea4f0f649f61" } |
| time_used | Int | 整个请求所花费的时间，单位为毫秒，此字段必定返回 | 100 |
| idcard_info | Json |
身份证识别的结果，此字段在idcard_mode = 0时不返回；如果用户中途中断了活体流程，则此字段也不返回
内容包括：
|
{
"idcard_mode": "1", "idcard_uneditable_field": idcard_valid_date", "idcard_number": "idcard_name": "陈AB", "idcard_valid_date": "2010.11.13-2020.11.13", "idcard_issued_by": "北京市公安局", "front_side": { "ocr_result": { "address": "北京市海淀区XXXX", "birthday": { "day": "2", "month": "6", "year": "1991" }, "gender": "男", "id_card_number": "xxxxxx19910602xxxx", "name": "陈XX", "race": "汉", "legality": { "ID Photo": 0.855, "Temporary ID Photo ":0, "Photocopy": 0.049, "Screen": 0.096, "Edited": 0 } }, "upload_times": 1 }, "back_side": { "ocr_result": { "issued_by": " 北京市公安局海淀分局", "valid_date": "2010.11.13-2020.11.13", "legality": { "ID Photo": 0.855, "Temporary ID Photo ": 0, "Photocopy": 0.049, "Screen": 0.096, "Edited": 0 } }, "upload_times": 2 }, "ocr_front_quality": { "gender": { "quality": 0.925, "logic": 0, "result": "男" }, "address": { "quality": 0.958, "logic": 0, "result": "xxx" }, "idcard_number": { "quality": 0.995, "logic": 0, "result": "xxxx" }, "name": { "quality": 0.996, "logic": 0, "result": "张三" }, "birth_month": { "quality": 0.971, "logic": 0, "result": "8" }, "birth_day": { "quality": 0.975, "logic": 0, "result": "31" }, "nationality": { "quality": 0.959, "logic": 0, "result": "汉" }, "birth_year": { "quality": 0.942, "logic": 0, "result": "1996" } }, "ocr_back_quality": { "issued_by": { "quality": 0.994, "logic": 0, "result": "xxxxx" }, "valid_date_end": { "quality": 0.995, "logic": 0, "result": "xxxx" }, "valid_date_start": { "quality": 0.995, "logic": 0, "result": "20140515" } } } |
| liveness_result | Json |
活体检测结果；如果用户中途中断了活体流程（status非“OK”），则此字段不返回
|
{
"result": "PASS/FAIL", "procedure_type": "video", "details": { "UPLOAD_TIMES": 5, "FACE_NOT _FOUND": 0, "LOW_FACE _QUALITY": 0, "INVALID_VIDEO _DURATION": 1, "SR_ERROR": 2, "NOT_SYNCHRONIZED": 1, "VIDEO_FORMAT _UNSUPPORTED": 0, "NO_AUDIO": 0 }, "face_genuineness": { "synthetic_face _confidence": 0.88, "synthetic_face _threshold": 0.5, "mask_confidence": 0.32, "mask_threshold": 0.5, "screen_replay _confidence": 0, "screen_replay _threshold": 0.5 } } |
| verify_result | Json |
人脸比对结果；如果用户中途中断了活体流程（status非“OK”）或comparison_type为-1（仅活体不比对），则此字段不返回
|
{
"verify_time": 1462259763, "result_faceid": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_idcard_photo": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "result_idcard _datasource": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, "id_exceptions": { "id_attacked": 0, "id_photo_ monochrome": 0 } } |
| images | Json |
活体检测得到的图像，调用时通过 return_image 来选择，或以jpg编码并用base64字符串返回，或返回为null；
当活体验证通过，存在比对结果且比对结果中error_message为计费字段时，图像才会返回
|
{ "image_idcard_back": "data:image/jpeg; base64,...", "image_idcard_front": "data:image/jpeg; base64,...", "image_best": "data:image/jpeg; base64,..." } |
| multifaces_tag | String |
仅当return_multifaces_tag参数为1时，返回此字段
|
0 |
| multifaces_image | String |
如果multifaces_tag=1，则返回一张包含多人脸的图像，以jpg编码并用base64字符串返回； 如果multifaces_tag=0，则返回空 |
"data:image/jpeg;base64,..." |
成功示例
{
"request_id": "1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c",
"status": "OK",
"biz_info": {
"biz_extra_data": "...",
"biz_id": "1462259748,52b13fb5-8dfb-4537-a62b-a641d5e929f1",
"biz_no": "cc47190f-5502-44a2-ab74-ea4f0f649f61"
},
"idcard_info": {
"idcard_mode": "1",
"idcard_uneditable_feild": "idcard_number,idcard_valid_date",
"idcard_number": "xxxxxx19910602xxxx",
"idcard_name": "陈AB",
"idcard_issued_by": "北京市公安局",
"front_side": {
"ocr_result": {
"address": "北京市海淀区XXXX",
"birthday": {
"day": "2",
"month": "6",
"year": "1991"
},
"gender": "男",
"id_card_number": "xxxxxx19910602xxxx",
"name": "陈XX",
"race": "汉",
"legality": {
"ID Photo": 0.855,
"Temporary ID Photo ": 0,
"Photocopy": 0.049,
"Screen": 0.096,
"Edited": 0
}
},
"upload_times": 1
},
"back_side": {
"ocr_result": {
"issued_by": "北京市公安局海淀分局",
"valid_date": "2010.11.13-2020.11.13",
"legality": {
"ID Photo": 0.855,
"Temporary ID Photo ": 0,
"Photocopy": 0.049,
"Screen": 0.096,
"Edited": 0
}
},
"upload_times": 2
}
},
"liveness_result": {
"procedure_type": "video",
"result": "PASS/FAIL/TIMEOUT",
"details": {
"UPLOAD_TIMES": 5,
"FACE_NOT_FOUND": 0,
"LOW_FACE_QUALITY": 0,
"INVALID_VIDEO_DURATION": 1,
"SR_ERROR": 2,
"NOT_SYNCHRONIZED": 1,
"VIDEO_FORMAT_UNSUPPORTED": 0,
"NO_AUDIO": 0
},
"face_genuineness": {
"synthetic_face_confidence": 0.88,
"synthetic_face_threshold": 0.5,
"mask_confidence": 0.32,
"mask_threshold": 0.5,
"screen_replay_confidence": 0,
"screen_replay_threshold": 0.5
}
},
"verify_result": {
"result_faceid": {
"confidence": 68.918,
"thresholds": {
"1e-3": 64,
"1e-4": 69,
"1e-5": 74,
"1e-6": 79.9
}
},
"result_ref1": {
"confidence": 68.918,
"thresholds": {
"1e-3": 64,
"1e-4": 69,
"1e-5": 74,
"1e-6": 79.9
}
},
"result_idcard_photo": {
"confidence": 68.918,
"thresholds": {
"1e-3": 64,
"1e-4": 69,
"1e-5": 74,
"1e-6": 79.9
}
},
"result_idcard_datasource": {
"confidence": 68.918,
"thresholds": {
"1e-3": 64,
"1e-4": 69,
"1e-5": 74,
"1e-6": 79.9
}
},
"id_exceptions": {
"id_attacked": 0,
"id_photo_monochrome": 0
}
},
"images": {
"image_idcard_back": "data: image/jpeg;base64,...",
"image_idcard_front": "data: image/jpeg;base64,...",
"image_best": "data: image/jpeg;base64,..."
},
"time_used": 93
}
失败示例
{
"error_message": "RESULT_NOT_FOUND",
"request_id": "1462259901,fa79992d-ca61-48de-aa50-ea337c6aad42",
"time_used": 4
}
# 错误码列表
GetResult 特有的 ERROR_MESSAGE
| HTTP状态代码 | 错误信息 | 说明 |
|---|---|---|
| 400 | RESULT_NOT_FOUND | 此错误类型表示传入的业务编号错误 |
| 400 | VIDEO_FACE_OCCLUDE | 上传的视频中人脸被遮挡 |
通用的ERROR_MESSAGE
| HTTP状态代码 | 错误信息 | 说明 |
|---|---|---|
| 403 | AUTHENTICATION_ERROR | api_key和api_secret不匹配 |
| 403 | AUTHORIZATION_ERROR:<reason> | api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。目前的<reason>有：Denied. （没有权限调用当前API） |
| 400 | MESSAGE_ENCRYPTION_ERROR | 云端对敏感信息加密失败 |
| 403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 |
| 400 | MISSING_ARGUMENTS:<key> | 缺少某个必选参数 |
| 403 | DATA_DESTROYED | 超过可查询时间或超过最多可查询次数 |
| 400 | BAD_ARGUMENTS:<key> | 某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长，etc.） |
| 404 | API_NOT_FOUND | 所调用的API不存在 |
| 500 | INTERNAL_ERROR | 服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务 |
该文档未解决您的疑问？
查看常见问题
查看常见问题