SDK-验证接口

verify

接口说明

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

此接口只适用于FaceID MegLiveStill SDK 2.0.0及以上版本，SDK 1.3版本及以下版本不需调用此接口。请调用get_result接口获取活体和比对结果，请参考对应版本历史文档（见该文档最下方）。

接口地址

POST  https://api.megvii.com/faceid/v3/sdk/verify

参数

参数名必选/可选类型参数说明
sign必选String调用此API而生成的签名 ； 生成签名本身可能存在特殊字符，需要对此参数进行 urlencode
sign_version必选String签名算法版本号，目前仅支持："hmac_sha1"
biz_token必选Stringget_biz_token接口获得的biz_token
meglive_data必选File此参数需要上传由FaceID MegLiveStill SDK 2.0.0及以上版本生成的数据，内容包括活体验证过程中的数据，和采集到的人脸数据。请不要对数据包做任何调整，直接提交接口即可。

返回值

参数类型说明
request_idString用于区分每一次请求的唯一的字符串。此字符串可以用于后续数据反查。此字段必定返回。
biz_noStringget_biz_token 接口传入的业务流水号
time_usedInt整个请求所花费的时间，单位为毫秒。此字段必定返回。
result_codeInt表示本次验证的结果状态码，参见下面详述
result_messageString开发者可通过此字段信息知晓具体的原因，参见下面详述
verificationJson当“verbose=1”，且“result状态码为1000、2000系列”时，本字段才会返回。
人脸比对的详细结果，可能的字段如下：
- idcard: Json类型, 表示活体照片和参考数据比对的结果，具体包括以下字段：
-- confidence: 综合分数，Float类型，取值［0，100］，数字越大表示风险越小。
-- thresholds: 一组用于参考的置信度阈值，Json类型，包含三个字段，均为Float类型、取值［0，100］:
--- 1e-3: 风险为千分之一的置信度阈值;
--- 1e-4: 风险为万分之一的置信度阈值;
--- 1e-5: 风险为十万分之一的置信度阈值;
--- 1e-6: 风险为百万分之一的置信度阈值;
- ref1: Json类型，表示活体照片和image_ref1的比对结果，仅当get_biz_token中存在image_ref1时返回，字段和idcard字段相同。
- ref2: Json类型，表示活体照片和image_ref2的比对结果，仅当get_biz_token中存在image_ref2时返回，字段和idcard字段相同。
attack_resultJson当“result状态码非4200系列”时，本字段才会返回：
"score"：Float类型，取值［0,1]。代表攻击的分数，分数越高表明攻击的可能性越大
"threshold"：Float类型，取值［0,1]。代表攻击的阈值
"result"：Bool类型，取值True或者False。代表云端攻击判断的结果，False代表不是攻击，True代表是攻击。
注：
当在App-GetBizToken中设置参数“force_compare=1”时，则该API会忽略云端的活体判断，用户需要自行通过此字段来判断是否是活体。
云端采用默认策略是判断score >= threshold时，代表此次可能是攻击。
imagesJson活体照片, 字段如下：
image_best: 活体检测获得的最优照片，base64编码。该照片会和参考照片或者用户上传的上传照片进行比对。
errorStringHTTP status code非200时返回，参见下面详述(HTTP状态码和对应的ERROR字段说明)

返回结果示例：成功

{
   "time_used":1448,
   "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
   },
   "request_id":"1531397565,39b19451-393c-4fc4-8fae-6dc74b2b00d7",
   "images":{
      "image_best":"xxxxxxxxxxx"
   },
   "biz_no":"",
   "result_message":"SUCCESS",
   "result_code":1000
}

返回结果示例：失败

{
    "error": "AUTHORIZATION_ERROR: INVALID_SIGN"
}

错误码说明：

Result_code&result_message说明

result_coderesult_message含义解释
1000SUCCESS待比对照片与参考照片比对结果是同一个人
2000PASS_LIVING_NOT_THE_SAME待比对照片与参考照片比对结果不是同一个人
3000NO_ID_CARD_NUMBER无此身份证号
3000ID_NUMBER_NAME_NOT_MATCH身份证号，姓名不匹配
3000NO_FACE_FOUND参考照片中找不到人脸
3000NO_ID_PHOTO无法获取参考照片
3000PHOTO_FORMAT_ERROR参考照片格式错误
3000DATA_SOURCE_ERROR其他参考照片错误
4100FAIL_LIVING_FACE_ATTACK未经过活体判断，可能的原因：是假脸攻击
4100VIDEO_LACK_FRAMES获取到的活体数据故障，请换一台手机重试
4100FAIL_EYES_CLOSE_DETECTION未通过闭眼检测，活体失败
4200BIZ_TOKEN_DENIED传入的 biz_token 不符合要求
4200AUTHENTICATION_FAIL鉴权失败
4200MOBILE_PHONE_NOT_SUPPORT手机在不支持列表里
4200SDK_TOO_OLDSDK版本过旧，已经不被支持
4200MOBILE_PHONE_NO_AUTHORITY没有权限（运动传感器、存储、相机）
4200USER_CANCELLATION用户活体失败，可能原因：用户取消了
4200USER_TIMEOUT用户活体失败，可能原因：验证过程超时
4200VERIFICATION_FAILURE用户活体失败，可能原因：验证失败
4200UNDETECTED_FACE用户活体失败，可能原因：未检测到人脸
4200ACTION_ERROR用户活体失败，可能原因：用户动作错误；
5000API_KEY_BE_DISCONTINUEDapi_key被停用
5000IP_NOT_ALLOWED不允许访问的IP
5000NON_ENTERPRISE_CERTIFICATION客户未进行企业认证
5000BALANCE_NOT_ENOUGH余额不足
5000MORE_RETRY_TIMES获取服务器配置时超过重试次数
5000ACCOUNT_DISCONTINUED用户帐号已停用
5000EXPIRED_SIGN签名过期
5000INVALID_SIGN无效的签名
5000REPLAY_ATTACK重放攻击，单次有效的签名被多次使用
6000USER_CANCEL用户取消
6000NO_CAMERA_PERMISSION没有打开相机的权限，请开启权限后重试
6000ILLEGAL_PARAMETER传入参数不合法
6000DEVICE_NOT_SUPPORT无法启动相机，请确认摄像头功能完好
6000INVALID_BUNDLE_ID信息验证失败，请重启程序或设备后重试
6000NETWORK_ERROR连不上互联网，请连接上互联网后重试
6000FACE_INIT_FAIL无法启动人脸识别，请稍后重试
6000LIVENESS_DETECT_FAILED活体检测不通过
6000NO_SENSOR_PERMISSION无法读取运动数据的权限，请开启权限后重试
6000INIT_FAILED初始化失败
9000LIVING_NOT_START活体验证没有开始
9000LIVING_IN_PROGRESS正在进行验证
9000LIVING_OVERTIME操作超时，由于用户在长时间没有进行操作

HTTP状态码和对应的ERROR字段说明

HTTP状态码ERROR字段说明
403INVALID_SIGN无效签名
403AUTHENTICATION_ERRORapi_key 和 api_secret 不匹配。
403AUTHORIZATION_ERROR:<reason>api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。
reason>取值：
API_KEY_BE_DISCONTINUED:api_key被停用
IP_NOT_ALLOWED：不允许访问的IP（预留设计）
MORE_RETRY_TIMES：超过重试次数
EXPIRED_SIGN：签名已过期
INVALID_SIGN：无效签名
其他可能的错误码，请预留处理方案 其他可能的错误码，请预留处理方案。
429CONCURRENCY_LIMIT_EXCEEDED并发数超过限制
400MISSING_ARGUMENTS:<key>缺少某个必选参数。
400BAD_ARGUMENTS:<key>某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
400BIZ_TOKEN_USEDbiz_token 已使用
400MEGLIVE_DATA_ERROR上传的meglive_data数据包解析失败。请将SDK产生的meglive_data数据包直接传递到此API，任何对数据包的修改都会导致数据包解析失败的问题。
400MEGLIVE_DATA_BIZ_TOKEN_NOT_MATCH上传的meglive_data包中的biz_token和传入参数biz_token不一致。
404API_NOT_FOUND所调用的API不存在。
413Request Entity Too Large客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本，不是json格式。
500INTERNAL_ERROR服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务

当前版本

  • v2.0.0

历史版本

← SDK-获取BizTokenSDK-错误码说明 →