# 调用URL

GET https://api-idn.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	此参数为可选参数，可在下面三种参数中选择，决定了是否返回活体图像数据： 0（默认）：不需要图像 1：需要返回最佳活体质量图(image_best）

# 返回值说明

参数	类型	说明	示例
request _id	String	API 调用的流水号	"1462259763, e2d2f8d6-204b-4c43 -92ea-1d62b071f83c"
status	String	表示目前FaceID Lite的使用状态： NOT_STARTED：get_token 之后，并没有调用过do方法，还没有开始验证 PROCESSING：正在进行FaceID Lite验证 WEBRTC_UNSUPPORTED：表示浏览器不支持引起失败 OK：完成了FaceID Lite验证（OK并不表示通过了验证，是流程正常结束） FAILED：验证流程未完成或出现异常注：在采用"flash"模式时，只要在照镜子环节30s内未通过验证，token状态即进入FAILED状态 CANCELLED：用户主动取消了验证流程 TIMEOUT：流程超时当处于“NOT_STARTED”或者“PROCESSING”状态时，liveness_result /verify_result字段均不会返回	"OK"
fail _reason	String	当“get_fail_reason”=1时，可获取“WEBRTC_UNSUPPORTED”失败原因 NETWORK_ERROR：因为网络问题无法连接 PERMISSIONS_ERROR ：用户拒绝摄像头权限或浏览器（APP）不支持唤起摄像头权限 SUPPORT_ERROR：浏览器不支持webRTC API 等	“NETWORK_ERROR”
biz_info	Json	包含：biz_id, biz_no, biz_extra_data biz_id：业务流串号，可以用于反查比对结果 biz_no：客户业务流水号，会在notify和return时原封不动的返回给客户 biz_extra_data：在调用 notify_url 和 return_url 时会返回的额外数据用户可以用此接口来传递一些额外信息。	{ "biz_extra_data": "...", "biz_id": "1462259748, 52b13fb5-8dfb-4537 -a62b-a641d5e929f1", "biz_no": "cc47190f-5502-44a2 -ab74-ea4f0f649f61" }
time _used	Int	整个请求所花费的时间，单位为毫秒，此字段必定返回	100
liveness _result	Json	活体检测结果；如果用户中途中断了活体流程，则此字段不返回 result：活体检测的结果，返回值分为两类： PASS：活体检测通过 FAIL：活体检测失败 procedure_type：返回本次活体所使用的活体验证方式： flash：通过炫彩活体方式进行活体验证 still：通过自拍一段人脸视频进行活体认证 details：活体检测结果的细节：当procedure_type取值为"flash"时： FACE_NOT_FOUND：<未检测到人脸次数> SIDE_FACE：<未正对摄像头次数（侧脸）> UPDOWN_FACE：<未正对摄像头次数（仰脸或低头）> EYE_OCCLUSION：<遮挡眼部次数> MOUTH_OCCLUSION：<遮挡嘴部次数> AWAY_FROM_CAMERA：<过于远离摄像头次数> CLOSE_TO_CAMERA：<过于靠近摄像头次数> FACE_OUT_OF_CAMERA：<未正视摄像头次数> HIGH_BRIGHTNESS：<光线过亮的次数> LOW_BRIGHTNESS：<光线过暗的次数> LOW_FACE_QUALITY：<视频中人脸质量太差的次数> 当procedure_type为"still"时，且为上传视频模式时： UPLOAD_TIMES：<活体视频上传次数> FACE_NOT_FOUND：<视频中没有检测到人脸的次数> LOW_FACE_QUALITY：<视频中人脸质量太差的次数> INVALID_VIDEO_DURATION：<视频时长不对的次数> SR_ERROR：<语音识别结果有误的次数> （静默活体可忽略） NOT_SYNCHRONIZED：<视频唇语识别错误的次数>（静默活体可忽略） NO_AUDIO：<视频无声音的次数> VIDEO_FORMAT_UNSUPPORTED：<视频格式错误的次数> VIDEO_FACE_INCONSISTENT：<视频中出现了不一致的人脸> face_genuineness：表示对假脸攻击的判定，它包含四组置信度和阈值，均为实数取值［0，1］区间。如果一个置信度大于其对应的阈值，则可以认为存在对应类型的假脸攻击 synthetic_face_confidence：<合成脸的置信度> synthetic_face_threshold：<合成脸的阈值> mask_confidence：<面具的置信度> mask_threshold：<面具的阈值> face_replaced：<是否存在换脸> Int类型，只取值0或1。0表示未检测出换脸攻击，1表示检测出了换脸攻击。注意：仅当实际使用静默非RTC或者视频活体方式才返回该字段。 screen_replay_confidence：<屏幕翻拍的置信度> screen_replay_threshold：<屏幕翻拍的阈值>	{ "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	人脸比对结果；如果用户中途中断了活体流程或comparison_type为-1，则此字段不返回 error_message：在做人脸比对的时候出现错误 null：表示没有出现错误 NO_FACE_FOUND：对应的图像没有检测到人脸。此错误会产生计费 DATA_SOURCE_ERROR：调用比对数据发生错误，一般来说是数据出错。出现此错误时建议停止业务，并立即联系FaceID客服或商务，待确认后再开启业务 INTERNAL_ERROR：服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务 result_ref[x]：活体采集人像与上传的image_ref[x]的比对结果 "confidence"：综合分数的置信度，Float类型，取值［0，100］，数字越大表示风险越小 “thresholds”：一组用于参考的置信度阈值，Object类型，包含四个字段，均为Float类型、取值［0，100］： “1e-3”：风险为千分之一的置信度阈值 “1e-4”：风险为万分之一的置信度阈值 “1e-5”：风险为十万分之一的置信度阈值 “1e-6”：风险为百万分之一的置信度阈值 verify_time：验证发生的时间戳（单位：秒），仅当return_verify_time=1时返回该字段。	{ "verify_time": 1462259763, "result_ref1": { "confidence": 68.918, "thresholds": { "1e-3": 64, "1e-4": 69, "1e-5": 74, "1e-6": 79.9 } }, }
images	Json	活体检测得到的图像，调用时通过 return_image 来选择，或以jpg编码并用base64字符串返回，或返回为null；当活体验证通过，存在比对结果且比对结果中error_message为计费字段时，图像才会返回 image_best：质量最佳的活体图像	{ "image_best": "data:image/jpeg; base64,..." }
multifaces_tag	String	仅当return_multifaces_tag参数为1时，返回此字段 0：单人脸 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"
    },
    "liveness_result": {
        "procedure_type": "flash",
        "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_ref1": {
            "confidence": 68.918,
            "thresholds": {
                "1e-3": 64,
                "1e-4": 69,
                "1e-5": 74,
                "1e-6": 79.9
            }
        },
    "images": {
        "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）
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客服或商务