接入文档
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调用成功后才返回)
可选 face_occlusion_detection String 用于设置是否开启人脸遮挡检测。0(默认):不开启;1:开启,如发生全程人脸遮挡,则活体不通过

# 返回值


参数

类型

说明

示例

request_id String API 调用的流水号 "1462259763,e2d2f8d6-204b-4c43-92ea-1d62b071f83c"
biz_no String

biz_no:客户业务流水号,此参数仅当调用时设置了biz_no参数才返回,即使API调用失败也返回,值与传入的biz_no保持完全一致。


time_used Int

整个请求所花费的时间,单位为毫秒。此字段必定返回。

100
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:<环境光线过暗>;
  • 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:
      • "id_attacked":Int类型,判别证件号码是否曾被冒用来攻击FaceID活体检测,  取值1表示曾被攻击、取值0表示未被攻击。攻击形态包括但不限于戴面具、换人 攻击、软件3D合成人脸等手段。若被判别为“是”,则有可能这个身份证号码目前 存在被利用的风险。注意:判别为“是”不意味证件持有者本人参与攻击,有可能 其证件被他人盗用而本人无感知。
      • "id_photo_monochrome":Int类型,参考照片的色彩判断,取值1表示   是黑白照片、取值0表示是彩色照片。参考数据存在一部分人像照片是黑白的现象, 黑白的照片会影响比对质量,一般来说将降低比对分数。本字段表达这样的异常。

        返回KYC验证相关的异常情况,如证件号码是否曾被冒用来攻击FaceID活体检测等问题。调用者可通过此对象增进对比对结果的解读。

        本对象仅在KYC验证时(comparison_type == 1)返回,返回包含如下字段:

{
    "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 Json

活体检测得到的图像,调用时通过 return_image 来选择,或以jpg编码并用base64字符串返回,或返回为null。


 


# 错误码列表

GetResult 特有的 ERROR_MESSAGE

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

# 通用的ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
403 AUTHENTICATION_ERROR api_key和api_secret不匹配。
403 AUTHORIZATION_ERROR: api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限。目前的有:Denied. (没有权限调用当前API)
403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制。
400 MISSING_ARGUMENTS: 缺少某个必选参数。
403 DATA_DESTROYED 超过可查询时间或超过最多可查询次数
400 BAD_ARGUMENTS: 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长,etc.)
404 API_NOT_FOUND 所调用的API不存在。
500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务。

# 计费规则

在JS-SDK回调成功产生计费,且在返回值(result_faceid或result_ref参数)有比对分数(confidence值)的情况下,每一笔请求都会计费。除此之外,比对错误出现以下返回信息也会计费。

返回信息(error_message) 含义解释 是否计费
NO_FACE_FOUND 姓名和身份证号码正确,但照片没有检测到人脸

NO_SUCH_ID_NUMBER 没有此身份证号码的记录。此错误会产生计费。
ID_NUMBER_NAME_NOT_MATCH 身份证号码与提供的姓名不匹配。此错误会产生计费。
IMAGE_ERROR_UNSUPPORTED_FORMAT: data_source 姓名和身份证号正确,但图片无法解析或者没有可比对图片。此错误会产生计费。
该文档未解决您的疑问?查看常见问题