接入文档
FaceID基础版
RAW纯接口接入
炫彩活体
获取结果
获取结果

successCallback回调,允许用户服务器向我方服务器调用Raw-GetResult结果

接口:Raw-GetResult

# 调用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:需要返回最佳质量图 (仅当 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 来选择,或以jpg编码并用base64字符串返回,或返回为null

# 返回示例

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> 缺少某个必选参数
403 DATA_DESTROYED 超过可查询时间或超过最多可查询次数
400 BAD_ARGUMENTS:<key> 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长,etc.)
404 API_NOT_FOUND 所调用的API不存在
500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务
该文档未解决您的疑问?查看常见问题