接入文档
FaceID高级版
APP接入
API接口
活体验证
活体验证

# 版本

5.0.0

# 描述

此接口上传待核验人员相关信息,从而获取对应活体验证结果。

# 调用URL

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

注意:在生产环境中,请使用 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字节
必选 data_type String 验证数据来源
  • 0:通过SDK 5.0.0以上进行活体验证
  • 1:自传照片进行活体验证
  • 待验证数据传入 data_type=0 条件必选 biz_token String get_biz_token接口获取的biz_token;用以标识本次核验数据对象
    data_type=1 条件必选 image File 通过传入自有照片进行验证时需传输
    条件必选 verify_id String verify场景id:本次验证请求相关配置在控台可设置,并将生成的id号在接口中使用
    条件必选 encryption_type String 是否开启传输数据加密,加密对应image,详细说明见:加密说明
  • 0:不开启
  • 1:SM2
  • 2:RSA
  • 可选 biz_token String get_biz_token接口获取的biz_token,用以串联业务请求

    # 返回值说明

    参数类别 参数 类型 参数说明
    #基础返回信息 request_id String API 调用的流水号
    biz_no String 传入的业务流水号,原封不动地返回
    time_used Int 整个请求所花费的时间,单位为毫秒。此字段必定返回
    error String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节,否则此字段不存在
    #状态码 result_code Int 表示本次验证的结果状态码。可结合result_code和result_message字段知晓具体的结果及原因:
    • 1000系列状态码活体验证通过
    • 4100系列状态码表示云端活体判断未通过
    • 4200系列状态码表示SDK活体图像采集失败
    • 其他结果,请预留处理方案,对于未来可能的错误,我们可能持续增加错误码
    :9000系列的返回优先级高于其他错误码
    #状态码描述 result_message String 可通过此字段信息知晓具体的原因。具体见:result_code & result_message 对照表
    #攻击结果 attack_result Json 当“result状态码非4200系列”时,本字段才会返回:
  • "result":Bool类型,取值True或者False。代表云端攻击判断的结果,False代表不是攻击,True代表是攻击
  • "score":Float类型,取值[0,1]。代表攻击的分数,分数越高表明攻击的可能性越大
  • "threshold":Float类型,取值[0,1]。代表攻击的阈值
  • 注:
    • 云端采用默认策略是判断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 疑似设备处于虚拟环境运行
    注:"device_info_tags"会随着业务发展进行拓展
    #人脸攻击信息描述 face_risk_info Json 人脸风险检测结果:
    "face_info_tags":Json类型;表示人脸攻击风险类型;
    人脸攻击Tag 说明
    is_photo 照片
    is_screen_remake 屏幕翻拍
    is_paper_cut 剪纸、贴纸
    is_paper_mask 纸面具
    is_3d_mask 3d面具
    is_facial_mask 面膜、口罩
    is_software_composition AI合成
    is_eye_close 闭眼
    is_change_face 动作过程换脸
    others 其他
    #附加返回信息 images String 一组照片列表,后续会根据采集的照片增加对应的照片字段
    • image_best:活体照片,base64编码
    video_key String 解密密钥,用于获取SDK端保存的视频及图片
    visual_attributes Json 附加属性:
    • “age”:预估核验人年龄
    • “gender”:预估核验人性别
    face Json 当选用image方式时返回待验证图片image的属性:
    • "quality":人脸质量
    • "quality_threshold":人脸质量阈值
    • "rect":人脸坐标点,json类型
    • "orientation":人脸方向

    # 返回值示例

    正确请求返回示例

    {
       "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}
       },
       "face_risk_info":{
          "face_info_tags":{"is_photo":0,"is_screen_remake":1,"is_paper_cut":0,"is_paper_mask":0,"is_3d_mask":0,"is_facial_mask":0,"is_software_composition":0,"is_eye_close":0,"is_change_face":0,"other":0}
       },
       "images":{
          "image_best":"xxxxxxxxxxx"
       },
       "video_key":"asdffff",
       "visual_attributes":{
          "age":16,
          "gender":0
       },
       "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 验证成功 是,详细计费请咨询商务
    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 没有权限(运动传感器、存储、相机)
    4200 USER_CANCELLATION 用户活体失败,原因可能如下:用户取消了、验证过程超时等原因
    4200 USER_TIMEOUT 用户活体失败,原因可能如下:用户取消了、验证过程超时等原因
    4200 VERIFICATION_FAILURE 用户活体失败,原因可能如下:用户取消了、验证过程超时等原因
    4200 UNDETECTED_FACE 用户活体失败,原因可能如下:用户取消了、验证过程超时等原因
    4200 ACTION_ERROR 用户活体失败,原因可能如下:用户取消了、验证过程超时等原因
    4200 GET_CONFIG_FAIL 用户活体失败,原因:读取配置失败

    # 错误码列表

    HTTP状态代码 错误信息 说明
    400 MISSING_ARGUMENTS:<key> 缺少某个必选参数
    400 BAD_ARGUMENTS:<key> 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 或者长度过长)
    注意:<meglive_data>错误代表当前token没有调用SDK,缺少活体数据报错
    400 IMAGE_ERROR_UNSUPPORTED_FORMAT 参数<param>对应的图像无法解析,有可能不是图像文件、或有数据破损。<param>为 image_ref1、 image_ref2中的一个。请注意:<param>只会有一项,即第一个满足条件的名称
    400 NO_FACE_FOUND 表示上传的 image 的图像中,没有检测到人脸
    400 INVALID_IMAGE_SIZE 客户上传的图像太大,具体是指像素尺寸的长或宽超过4096像素。<param>为 image
    400 LOW_QUALITY image图片质量太差
    400 MULTIPLE_FACES image图片中有多张人脸
    400 MEGLIVE_DATA_ERROR  数据包解析失败
    400 DATA_APPKEY_NOT_MATCH 上传的meglive_data包中的key/token与对应key不一致
    400 KEY_NOT_FOUND is_encryption 开启加密,但未配置加密公钥和解密私钥
    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验证的权限,但是本次请求依然尝试调用了
    • DENIED:无权限调用当前API
    • EXPIRED_SIGN:签名已过期
    • INVALID_SIGN:无效签名
    • NO_LIVENESS_PERMISSION:没有活体权限,但是本次请求依然尝试调用了
    • 其他可能的错误码,请预留处理方案
    403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
    404 API_NOT_FOUND 所调用的API不存在
    413 Request Entity Too Large 客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本,不是json格式
    500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务
    该文档未解决您的疑问?查看常见问题