# 调用URL

https://api.megvii.com/faceid/lite/raw/get_result

注意：在生产环境中，请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路，存在安全风险，请勿在生产环境中使用。在生产环境中使用HTTP方式的，将无法得到服务可靠性保障。

# 调用方法

GET

# 参数

必选/可选	参数	类型	说明
必选	api_key	String	调用此 API 的 api_key
必选	api_secret	String	调用此 API 的 api_key 的 secret
必选	token	String	通过 get_token 返回的令牌
可选	return_image	String	此参数为可选参数，决定了是否返回从视频中截取的最佳质量图像： 0（默认）：不需要图像； 1：需要返回1张最佳质量图 (仅当API调用成功后才返回) 2：需要返回2张最佳质量图 (仅当API调用成功后才返回)

# 返回值说明

参数	类型	说明	示例
request_id	String	API调用的流水号	"1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c"
biz_no	String	biz_no：客户业务流水号，此参数仅当调用时设置了biz_no参数才返回，即使API调用失败也返回，值与传入的biz_no保持完全一致
time_used	Int	整个请求所花费的时间，单位为毫秒，此字段必定返回	100
status	String	NOT_STARTED：未进行FaceID炫彩活体验证； PROCESSING：正在进行FaceID炫彩活体验证； OK：完成了FaceID炫彩活体验证； FAILED：炫彩活体验证失败，如：炫彩活体验证照镜子环节30s内未通过验证；	"status": "NOT_STARTED"
liveness_result	Json	活体检测结果；如果用户中途中断了活体流程，则此字段不返回 result：活体检测的结果，返回值分为两类： PASS：活体检测通过； FAIL：活体检测失败； details：活体检测结果的细节（该结果不代表活体不通过，仅代表用户在活体过程中错误行为次数的记录）： 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：<视频中人脸质量太差的次数> score：炫彩活体检测得分情况 flash_attack：炫彩攻击分数，反映上传的视频流打光色彩序列与系统下发序列的不一致程度 living_attack：活体攻击分数，表示该用户是攻击的可信度
verify_result	Json	人脸比对结果；如果用户中途中断了活体流程，则此字段不返回 error_message：在做人脸比对的时候出现错误 null：表示没有出现错误 NO_SUCH_ID_NUMBER：没有此身份证号码的记录。此错误会产生计费 ID_NUMBER_NAME_NOT_MATCH：身份证号码与提供的姓名不匹配。此错误会产生计费 IMAGE_ERROR_UNSUPPORTED_FORMAT: data_source：姓名和身份证号正确，但图片无法解析或者没有可比对图片。此错误会产生计费 NO_FACE_FOUND:<param>：参数<param>对应的图像没有检测到人脸。此错误会产生计费 DATA_SOURCE_ERROR：调用比对数据发生错误，一般来说是数据出错。出现此错误时建议停止业务，并立即联系FaceID客服或商务，待确认后再开启业务 INTERNAL_ERROR：服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务 result_faceid：KYC验证的综合分数 "confidence"：综合分数的置信度，Float类型，取值［0，100］，数字越大表示风险越小 “thresholds”：一组用于参考的置信度阈值，Object类型，包含四个字段，均为Float类型、取值［0，100］： “1e-3”：风险为千分之一的置信度阈值 “1e-4”：风险为万分之一的置信度阈值 “1e-5”：风险为十万分之一的置信度阈值 “1e-6”：风险为百万分之一的置信度阈值 result_ref[x]：活体采集人像与上传的image_ref[x]的比对结果；（同result_faceid） id_exceptions：返回KYC验证相关的异常情况，如证件号码是否曾被冒用来攻击FaceID活体检测等问题。调用者可通过此对象增进对比对结果的解读本对象仅在KYC验证时（comparison_type == 1)返回，返回包含如下字段： "id_attacked"：Int类型，判别证件号码是否曾被冒用来攻击FaceID活体检测，取值1表示曾被攻击、取值0表示未被攻击。攻击形态包括但不限于戴面具、换人攻击、软件3D合成人脸等手段。若被判别为“是”，则有可能这个身份证号码目前存在被利用的风险。注意：判别为“是”不意味证件持有者本人参与攻击，有可能其证件被他人盗用而本人无感知 "id_photo_monochrome"：Int类型，参考照片的色彩判断，取值1表示是黑白照片、取值0表示是彩色照片。参考数据存在一部分人像照片是黑白的现象，黑白的照片会影响比对质量，一般来说将降低比对分数，本字段表达这样的异常返回KYC验证相关的异常情况，如证件号码是否曾被冒用来攻击FaceID活体检测等问题。调用者可通过此对象增进对比对结果的解读	{ "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 } }
image_best	String	本字段仅调用成功且return_image字段配置为1或者2时才返回，返回为将会用于人脸比对的视频中的最佳质量的人脸照片。采用Base64字符串返回，图像格式为JPEG。在异常情况下，该字段有可能返回null
image_best_2	String	本字段仅调用成功且return_image字段配置为2时才返回，返回为质量最佳的另一张活体图像。采用Base64字符串返回，图像格式为JPEG。在异常情况下（如只存在一张符合质量的图片），该字段有可能返回null
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,..."

# 返回示例

status为"OK"时:

{
"status": "ok",
"time_used":2,
"image_best":"data:image/jpeg;base64,",
"liveness_result":{
"score":{
"flash_attack":0.5,
"living_attack":0.5
},
"result":0.5,
"details":0.5
},
"request_id":"1629684531,ec2fc2a6-01fc-4ecf-82fe-f26c5bf1b2ed",
"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
    }
},
"biz_no":"c22fe4e0-66ba-4078-bd9b-3b1a20628f8d"
}

status为"Failed"时:

{
"status": "Failed",
"time_used":2,
"image_best":"data:image/jpeg;base64,",
"liveness_result":{
"score":{
"flash_attack":0.5,
"living_attack":0.5
},
"result":0.5,
"details":0.5
},
"request_id":"1629684531,ec2fc2a6-01fc-4ecf-82fe-f26c5bf1b2ed",
"verify_result":{
 
},
"biz_no":"c22fe4e0-66ba-4078-bd9b-3b1a20628f8d"
}

status为"NOT_STARTED"时:

{
"status": "NOT_STARTED",
"time_used":2,
"image_best":"data:image/jpeg;base64,",
"liveness_result":{
"score":{
"flash_attack":null,
"living_attack":null
},
"result":null,
"details":null
},
"request_id":"1629684531,ec2fc2a6-01fc-4ecf-82fe-f26c5bf1b2ed",
"verify_result":{
 
},
"biz_no":"c22fe4e0-66ba-4078-bd9b-3b1a20628f8d"
}

# 错误码列表

GetResult 特有的 ERROR_MESSAGE

HTTP 状态代码	错误信息	说明
400	RESULT_NOT_FOUND	此错误类型表示传入的业务编号错误

通用的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>	缺少某个必选参数
400	MESSAGE_ENCRYPTION_ERROR	云端对敏感信息加密失败
403	DATA_DESTROYED	超过可查询时间或超过最多可查询次数
400	BAD_ARGUMENTS:<key>	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长，etc.）
404	API_NOT_FOUND	所调用的API不存在
500	INTERNAL_ERROR	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务