接入文档
FaceID增强版
常见问题
老客户升级
基础版V3升级
活体验证
活体验证

# 版本

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：自传照片进行身份核验验证
  • 3：通过SDK V3 进行活体验证
    		•
    待验证数据传入 data_type=0 条件必选 biz_token String get_biz_token接口获取的biz_token，用以标识本次核验数据对象
    可选 encryption_type String 是否开启传输数据加密，详细说明见：加密说明
  • 0：不开启
  • 1：SM2
  • 2：RSA
    		•
    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，用以串联业务请求
    data_type=3 条件必选 meglive_data String 通过V3 SDK采集的数据进行验证时需传入
    可选 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"会随着业务发展进行拓展
    #附加返回信息 images String 一组照片列表，后续会根据采集的照片增加对应的照片字段
    • image_best：活体照片，base64编码
    video_key String 解密密钥，用于获取SDK端保存的视频及图片
    face Json 当选用rawimage方式时返回待验证图片image的属性：
    • "quality"：人脸质量
    • "quality_threshold"：人脸质量阈值
    • "rect"：人脸坐标点，json类型
    • "orientation"：人脸方向

    # 返回值示例

    正确请求返回示例

    {
   "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
   "biz_no":"",
   "time_used":1448,
   "result_code":1000,
   "result_message":"SUCCESS",
   "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}
   },
   "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 验证成功 是，详细计费请咨询商务
    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客服或商务
    该文档未解决您的疑问？查看常见问题
    Copyright © 2024 北京旷视科技有限公司