接入文档
FaceID增强版
APP接入
API接口
比对认证
比对认证

# 版本

5.0.0

# 描述

此接口用于将FaceID MegLiveStill SDK 所获得的数据进行上传,并获取活体验证、人脸比对、攻击防范等结果信息。

# 调用URL

https://api.megvii.com/faceid/v5/sdk/verify

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

# 调用方法

POST  注意:用 form-data 格式请求

# 权限

仅当用户接入FaceID产品后,才能调用FaceID各Web API。接入FaceID的流程请咨询FaceID商务人员。

# 参数

必选/可选 参数 类型 参数说明
必选 sign String 调用此API客户的签名,具体的签名产生方式请查阅App-鉴权说明
必选 sign_version String 签名算法版本号,请传递:hmac_sha1
可选 biz_no String “默认为空”。客户业务流水号,建议设置为您的业务相关的流水串号并且唯一,会在return时原封不动的返回给您的服务器,以帮助您确认对应业务的归属。此字段不超过128字节
必选 comparison_type String 本次请求的验证方式
  • 0:人脸比对
  • 1:人脸核身
  • 2:实证核身
  • 必选 data_type String 验证数据来源
  • 0:通过SDK 5.0.0以上进行身份核验验证
  • 1:自传照片进行身份核验验证
  • 必选 verify_id String verify场景id:本次验证请求相关配置在控台可设置,并将生成的id号在接口中使用
    必选 encryption_type String 是否开启传输数据加密,详细说明见:加密说明
  • 0: 不开启
  • 1: SM2
  • 2: RSA
  • 待验证数据传入 data_type=0 条件必选 biz_token String get_biz_token接口获取的biz_token;用以标识本次核验数据对象
    data_type=1 条件必选 image File 通过传入自有照片进行验证,需传输
    可选 biz_token String get_biz_token接口获取的biz_token,用以串联业务请求
    参考数据传入 comparison_type=1(人身核验) 条件必选 idcard_name String 需要核实对象的姓名,使用UTF-8编码
    条件必选 idcard_number String 需要核实对象的证件号码,也就是一个18位长度的字符串
    可选 image_ref1 File 由应用方提供的参照人脸照片。如果在image_ref1中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对
    comparison_type=0(人脸比对) 条件必选 uuid String 如果应用方不使用参考数据进行比对,则上传此字段,用于标志本次识别对应的用户的唯一ID,要求不长于128字节。建议您对来自同一用户的比对请求使用同样的ID,这非常有利于您反查验证结果以及获得更好的数据报表体验
    条件必选 image_ref1 File 由应用方提供的参照人脸照片。如果在image_ref1、image_ref2中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对
    可选 image_ref2 File 由应用方提供的参照人脸照片。如果在image_ref1、image_ref2中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对
    comparison_type=2(实证核身) 可选 image_ref1 File 由应用方提供的参照人脸照片。如果在image_ref1中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将选择最大人脸进行比对

    # 返回值说明

    参数类别 参数 类型 参数说明
    #基础返回信息 request_id String API 调用的流水号
    biz_no String 传入的业务流水号,原封不动地返回
    time_used Int 整个请求所花费的时间,单位为毫秒。此字段必定返回
    user_faced_time String 用户刷脸发生的时间
    error String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节,否则此字段不存在
    #状态码 result_code Int 表示本次验证的结果状态码。可结合result_code和result_message字段知晓具体的结果及原因:
    • 1000系列状态码表示比对完成,活体验证通过,比对通过
    • 2000系列状态码表示比对完成,活体验证通过,比对失败
    • 3000系列状态码表示在比对的时候,参考数据调用情况
    • 3100系列状态码表示参考数据调用出错
    • 4100系列状态码表示云端活体判断未通过
    • 4200系列状态码表示SDK活体图像采集失败
    • 其他结果,请预留处理方案,对于未来可能的错误,我们可能持续增加错误码
    :9000系列的返回优先级高于其他错误码;当控制台开启“假脸仍比对”,则不返回4100活体结果,仅返回比对结果
    #状态码描述 result_message String 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表
    #比对结果 verification Json
  • "idcard":KYC验证的综合分数
    • "confidence":Float类型,取值[0,100],数字越大表示风险越小
    • “thresholds”:一组用于参考的置信度阈值,Object类型,包含三个字段,均为Float类型、取值[0,100]:
      • “1e-3”:风险为千分之一的置信度阈值
      • “1e-4”:风险为万分之一的置信度阈值
      • “1e-5”:风险为十万分之一的置信度阈值
      • “1e-6”:风险为百万分之一的置信度阈值
  • ref1:活体采集人像与上传的image_ref1的比对结果(仅当verify中存在image_ref1时返回,返回结果同idcard字段)
  • ref2:活体采集人像与上传的image_ref2的比对结果(仅当verify中存在image_ref2时返回,返回结果同idcard字段)
  • #攻击结果 attack_result Json
  • "result":Bool类型,取值True或者False。代表云端攻击判断的结果,False代表不是攻击,True代表是攻击
  • "score":Float类型,取值[0,1]。代表攻击的分数,分数越高表明攻击的可能性越大
  • "threshold":Float类型,取值[0,1]。代表攻击的阈值
  • 注:
    • 当在控制台Verify场景中开启假脸仍比对时,则该API会忽略云端的活体判断进行比对业务
    • 云端采用默认策略是判断score >= threshold时,代表此次可能是攻击
    #设备攻击信息描述 device_risk_info Json 设备风险检测结果:
  • "device_info_level":string类型,0:表示未检测到风险;1:表示中风险(建议业务核查);2:表示高风险(Face ID直接拦截。如开启设备风险检测且进行高风险拦截,则此类风险请求会被拦截)
  • "device_info_tags":Json类型;表示设备风险类型
  • 设备风险Tag 说明
    is_root 疑似设备被root
    is_hook 疑似设备被hook
    is_injection 疑似设备被注入
    is_virtual_environment 疑似设备处于虚拟环境运行
    is_double_open 疑似设备双开
    is_group_control_risk 疑似群控设备风险
    is_non_system_user 疑似非系统用户
    is_location_spoofed 疑似伪造地理位置
    is_using_vpn 疑似使用VPN软件
    is_using_agent 疑似使用代理软件
    is_usb_Inserted 疑似设备处于USB插线状态
    is_screen_casting 疑似设备处于投屏状态
    is_anomalous_behavior 疑似设备近期识别有异常行为
    is_other_risks 其他设备风险
    注:"device_info_tags"会随着业务发展进行新增、修改、删除等扩展
    #附加返回信息 images Json 一组照片列表,后续会根据采集的照片增加对应的照片字段
    • image_best:活体照片,base64编码
    video_key String 解密密钥,用于获取SDK端保存的视频及图片
    face Json 当选用image方式时返回待验证图片image的属性:
    • "quality":人脸质量
    • "quality_threshold":人脸质量阈值
    • "rect":人脸坐标点,json类型
    • "orientation":人脸方向
    visual_attributes Json 附加属性:
    • “age”:预估核验人年龄
    • “gender”:预估核验人性别
    • “age_image_ref1”:预估参照人脸图ref1年龄(comparison_type=0时,返回)
    • “gender_image_ref1”:预估参照人脸图ref1性别(comparison_type=0时,返回)
    注: 仅当在控制台Verify场景中开启“比对风险检测”时,返回该参数
    verify_risk_info Json 比对风险提示结果:
    • "verify_info_tags":Json类型;表示活体图比对风险类型
    注: 仅当在控制台Verify场景中开启“比对风险检测”时,返回该参数
    比对风险Tag 说明
    is_gender_risk string类型,0:表示活体图与比对图性别一致;1:表示活体图与比对图性别不一致;(comparison_type=1或2,则活体图与身份证性别比对;comparison_type=0,则活体图与ref1图性别比对)
    is_age_risk string类型,0:表示活体图与比对图年龄差异不大;1:表示活体图与比对图年龄差异较大;(一般指的是年龄差距在10岁及以上,具体根据阈值设定。comparison_type=1或2,则活体图与身份证年龄比对;comparison_type=0,则活体图与ref1图年龄比对)

    # 返回值示例

    正确请求返回示例

    {
       "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
       "biz_no":"",
       "time_used":1448,
       "user_faced_time":2021-12-21 10:11:11,
       "result_code":1000,
       "result_message":"SUCCESS",
       "verification":{
          "idcard":{
             "confidence":86.63057,
             "thresholds":{
                "1e-3":62.168713,
                "1e-5":74.39926,
                "1e-4":69.31534,
                "1e-6":78.038055
             }
          }
       },
       "attack_result":{
          "score":0.26,
          "threshold":0.5,
          "result":False
       },
       "device_risk_info":{
          "device_info_level": "2",
          "device_info_tags": {"is_root":0,"is_hook":1,"is_injection":1,"is_virtual_environment":1,"is_other_risks":1}
       },
       "images":{
          "image_best":"xxxxxxxxxxx"
       },
       "video_key":"asdffff"
       "face":{
          "quality":38.221,
          "quality_threshold":30.1,
          "rect":{
             "left":0.18,
             "top":0.18,
             "width":0.596,
             "height":0.596
           },
          "orientation":90
       }
    }
    

    失败请求返回示例

    {
        "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
    }
    

    # result_code & result_message 对照表

    result_code result_message 含义解释 是否计费
    1000 SUCCESS 验证成功 是,详细计费请咨询商务
    2000 PASS_LIVING_NOT_THE_SAME 通过了活体检测,但是经过验证,待比对照片与其他照片中的至少一张,不是同一个人
    3000 NO_ID_CARD_NUMBER 无此身份证号
    3000 ID_NUMBER_NAME_NOT_MATCH 证件号码和姓名不匹配
    3000 NO_FACE_FOUND 姓名和身份证号码正确,但照片没有检测到人脸
    3000 NO_ID_PHOTO 找不到参考照片
    3000 PHOTO_FORMAT_ERROR 参考照片格式错误
    3000 DATA_SOURCE_ERROR 参考数据出现错误
    4100 FAIL_LIVING_FACE_ATTACK 未经过活体判断,可能的原因:是假脸攻击
    4100 VIDEO_LACK_FRAMES 获取到的活体数据故障,请换一台手机重试
    4200 BIZ_TOKEN_DENIED 传入的 biz_token 不符合要求
    4200 AUTHENTICATION_FAIL 鉴权失败
    4200 MOBILE_PHONE_NOT_SUPPORT 手机不在支持列表里
    4200 SDK_TOO_OLD SDK版本过旧,已经不被支持
    4200 MOBILE_PHONE_NO_AUTHORITY 没有权限(运动传感器、存储、相机)
    4300 NO_FOUND_EID_REF 实证核身没有找到数据源,原因可能如下:没有调用NFC查询后仍然调用人脸比对服务

    # 错误码列表

    HTTP状态代码 错误信息 说明
    400 MISSING_ARGUMENTS:<key> 缺少某个必选参数
    400 BAD_ARGUMENTS:<key> 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长)
    注意:<meglive_data>错误代表当前token没有调用SDK,缺少活体数据报错
    400 IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> 参数<param>对应的图像无法解析,有可能不是图像文件、或有数据破损。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称
    400 NO_FACE_FOUND:<param> 表示上传的 image_ref 的图像中,没有检测到人脸。<param>为 image_ref1、 image_ref2、image中的一个。请注意:<param>只会有一项,即第一个满足条件的名称
    400 INVALID_IMAGE_SIZE:<param> 客户上传的图像太大,具体是指像素尺寸的长或宽超过4096像素。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称
    400 LOW_QUALITY image图片质量太差
    400 MULTIPLE_FACES image图片中有多张人脸
    400 MEGLIVE_DATA_ERROR  上传的活体数据解析失败。请将SDK产生的meglive_data数据包直接传递到此API,任何对数据包的修改都会导致数据包解析失败的问题
    400 DATA_APPKEY_NOT_MATCH 上传的meglive_data包中的key/token与对应key不一致
    400 KEY_NOT_FOUND encryption_type开启加密,但未配置加密公钥和解密私钥
    400 FMP_CONTENT_TYPE_ERROR 视频错误,请重试或更换手机重试
    403 AUTHENTICATION_ERROR 无效签名
    403 AUTHORIZATION_ERROR:<reason> api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限
    <reason>取值:
    • API_KEY_BE_DISCONTINUED:api_key被停用
    • IP_NOT_ALLOWED:不允许访问的IP(预留设计)
    • LIMIT_REACHED:这个api_key对当前API的调用量达到上限。仅当api_key为测试key
    • MORE_RETRY_TIMES:比对重试次数达到上限
    • NO_VERIFY_PERMISSION:没有人脸比对的权限,但是本次请求依然尝试调用了
    • NO_DATA_SOURCE_PERMISSION:没有KYC验证的权限,但是本次请求依然尝试调用了
    • NO_EID_PERMISSION:没有实证核身的权限,但是本次请求依然尝试调用了
    • DENIED:无权限调用当前API
    • EXPIRED_SIGN:签名已过期
    • INVALID_SIGN:无效签名
    • NO_LIVENESS_PERMISSION:没有活体权限,但是本次请求依然尝试调用了
    • 其他可能的错误码,请预留处理方案
    403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
    404 API_NOT_FOUND 所调用的API不存在
    413 Request Entity Too Large 客户发送的请求大小超过了10MB限制或单张照片大小超过了2MB。该错误的返回格式为纯文本,不是json格式
    500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务
    该文档未解决您的疑问?查看常见问题