接入文档
FaceID海外基础版(中文)
RAW纯接口接入
静默活体
人脸比对
人脸比对

# 描述

用于Raw-ValidateStill API之后的活体结果验证、人脸比对、攻击判断等,并相应的返回结果。

仅当appkey有网页人脸核身API服务的视频验证、或自拍验证权限时,才可以调用此API,否则返回错误码 403(AUTHORIZATION_ERROR:Denied)。

# 调用URL

https://api-sgp.megvii.com/faceid/lite/raw/verify

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

# 调用方法

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

# 参数

必选/任选 参数 类型 参数说明
必选 api_key String 调用此API的api_key
必选 api_secret String 调用此API的api_key的secret
必选 token String Raw-ValidateStill API返回的token_still作为参数
可选 biz_no String 用于标志一次验证流程,不超过128字符。如果要使用此参数,强烈建议对一次验证流程中调用的API(比如Raw-ValidateStill和Raw-Verify)使用同一个biz_no,对不同的验证流程使用不同的biz_no
必选                     comparison_type String 本参数可选值如下,传递其他值调用将返回错误码400(BAD_ARGUMENTS)
  • “0”表示人脸比对,表示将与自己提供的照片(参数image_ref[x])比对。请注意:如果appkey没有人脸比对的权限,设置此值将返回错误码 403(AUTHORIZATION_ERROR:Denied)
必选 uuid String 如果用户不使用参考数据进行比对,则上传此字段,用于标志本次识别对应的用户的唯一ID,要求不长于512字节。建议您对来自同一用户的 比对请求使用同样的ID,这非常有利于您反查验证结果以及获得更好的数据报表查看体验。
必选 image_ref[x] File 多张由您自己提供的参照人脸照片。x表示此参数可重复多次,其中1<=x <= 3,即表示可以传最多三张参照人脸照片(参数分别为image_ref1、image_ref2、image_ref3)。如果在image_ref[x]中的任一张图片里没有找到人脸,将返回错误码400(NO_FACE_FOUND);如果这些图片中任一张中有多张脸,将返回错误码400(MULTIPLE_FACES)
可选 multi_oriented_detection String 决定对于image_ref[x]参数对应的图片,当检测不出人脸时,是否旋转90度、180度、270度后再检测人脸。本参数取值只能是 “1” 或 "0" (默认值为“0”):
  • “1”:要旋转检测;
  • “0”:不旋转;
  • 其他值:返回错误码400(BAD_ARGUMENTS)
请注意:设置此参数为1可能会轻微增加误检人脸的概率,如果您明确您的业务场景里不存在非正向的人脸图片、或概率极低,建议勿设置此参数
可选 fail_when_ref_multiple_faces String 用于设置参照人脸图(image_ref[x])检测到多张人脸时,是否立即返回错误,本参数取值如下:
  • “1”:立即返回错误吗400(MULTIPLE_FACES:<param>)
  • “0”:取最大脸继续对比
注:本参数默认值为“1”

# 返回值说明

字段 类型 说明
request_id String 用于区分每一次请求的唯一的字符串。此字符串可以用于后续数据反查。此字段必定返回
time_used Int 整个请求所花费的时间,单位为毫秒。此字段必定返回
biz_no String 此参数仅当调用时设置了biz_no参数才返回,但是如果设置了则即使API调用失败也返回,值与传入的biz_no保持完全一致
liveness Object 本字段结构体表示流程验证结果、活体检测的结果 本字段结构体包含两个字段:
  • procedure_validation:流程验证的结果,它取如下值:
    • "PASSED":流程验证通过
    • "VIDEO_SR_ERROR": 视频识别结果与要求不符
    • "VIDEO_FACE_INCONSISTENT": 视频过程中的人脸不一致
  • face_genuineness:假脸攻击判定的结果,它取如下值:
    • “PASSED”:不是假脸
    • “MASK”:面具攻击
    • “SCREEN_REPLAY”:屏幕翻拍
    • “FACEGEN”:软件合成脸
请注意:
  • 一般仅在procedure_validation、face_genuineness 都为“PASSED”时,才认为活体认定通过
  • 如果procedure_validation不为PASSED,将不返回face_genuineness字段,也不会进行人脸比对
  • 随产品迭代,本结构体中各字段可能出现新的取值,或者下线已存在的取值,请在集成开发时务必保留灵活性
result_ref[x] Object 本字段仅在设置了image_ref1、image_ref2或image_ref3时才返回、且只在接口被成功调用时返回。返回image_ref[x]与待验证人脸照的比对结果,分别为result_ref1、result_ref2、result_ref3。 返回综合验证分数。此字段只在接口被成功调用时返回。
  • "confidence":Float类型,取值[0,100],数字越大表示风险越小
  • “thresholds”:一组用于参考的置信度阈值,Object类型,包含四个字段,均为Float类型,取值[0,100]:
    • “1e-3”:风险为千分之一的置信度阈值
    • “1e-4”:风险为万分之一的置信度阈值
    • “1e-5”:风险为十万分之一的置信度阈值
    • “1e-6”:风险为百万分之一的置信度阈值
请注意:阈值不是静态的,每次比对返回的阈值不保证相同,所以没有持久化保存阈值的必要,更不要将当前调用返回的confidence与之前调用返回的阈值比较 关于阈值选择,以下建议仅供参考:
  • 阈值选择主要参考两个因素:业务对安全的要求和对用户体验的要求。严格的阈值对应更高的安全度,但是比对通过率会下降,因此更容易出现用户比对多次才通过的情况,用户体验会有影响;较松的阈值带来一次通过率会提升,用户体验更好,但是出现非同一个人的概率会增大,安全性会有影响。请按业务需求偏好慎重选择
  • “1e-3”阈值是较松的阈值。如果confidence低于“1e-3”阈值,我们不建议认为是同一个人;如果仅高于“1e-3”阈值,勉强可以认为是同一个人。这个阈值主要针对对安全性相对要求较低的场景(比如在分项业务有独立密码保护的情况下刷脸登陆app),或者原则上安全性要求高、但在一个具体流程里如果发生安全事故后果不严重的场景(比如“转账”场景安全性要求高、但是当前转账的金额很小)
  • “1e-5”、“1e-6”阈值都是较严格的阈值,一般来说置信度大于“1e-5”阈值就可以相当明确是同一个人。我们建议使用“1e-5”到关键的、高安全级别业务场景中,比如大额度的借款或者转账。“1e-6”则更加严格,适用于对安全性要求比较极端的场景
  • “1e-4”阈值的严格程度介于“1e-3”阈值与“1e-5”阈值之间
  • 如果对阈值选择存疑,请咨询FaceID商务或技术支持团队
error_message String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节。否则此字段不存在

成功

{
  "time_used": 1943, 
  "liveness": {
    "procedure_validation": "PASSED", 
    "face_genuineness": "PASSED"
  }, 
  "result_ref1": {
    "confidence": 59.873, 
    "thresholds": {
      "1e-3": 65.3, 
      "1e-5": 76.5, 
      "1e-4": 71.8, 
      "1e-6": 79.9
    }
  }, 
  "request_id": "1490012180,eca42fde-ef75-4fb3-8a98-6299e5bf8c4b"
}

失败

{
  "time_used": 2,
  "biz_no": "3149525e-2c24-4862-8e9f-92040595f0a4",
  "error_message": "INVALID_TOKEN",
  "request_id": "1490026804,adcb6619-c8f0-49ae-a643-00dc77356184"
}

# 错误码列表

特有的 ERROR_MESSAGE

HTTP状态代码 错误信息 说明 是否计费
400 IMAGE_ERROR_UNSUPPORTED_FORMAT:<param> 参数<param>对应的图像无法正确解析,有可能不是一个图像文件、或有数据破损。<param>为 data_source、 image_ref1、 image_ref2、 image_ref3中的一个 当<param>取值为data_source时,表示参考数据的图片无法解析、或者参考数据没有照片;当<param>取其他值时对应相应的参数 是 (仅当<param>为 data_source时)
400 NO_FACE_FOUND:<param> 参数<param>对应的图像没有检测到人脸 是 (仅当<param>为 data_source时)
400 INVALID_TOKEN token不存在、过期、或格式错误、或不是同一个API Key调用的所返回的token
400 INVALID_IMAGE_SIZE:<param> 客户上传的图像太大。具体是指像素尺寸的长或宽超过4096像素。<param>对应图像太大的那个参数的名称。请注意:如果图片存储尺寸大于2MB,会触发错误413(Request Entity Too Large)
400 MULTIPLE_FACES:<param> 参数<param>对应的图像检测到了多张人脸

通用的ERROR_MESSAGE

HTTP状态代码 错误信息 说明 是否计费
403 AUTHENTICATION_ERROR api_key和api_secret不匹配
403 AUTHORIZATION_ERROR:<reason> api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限 目前的<reason>有:
  • Denied(没有权限调用当前API)
403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制
400 MISSING_ARGUMENTS: <key> 缺少某个必选参数
400 BAD_ARGUMENTS:<key> 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 长度过长;不允许的输入值)
404 API_NOT_FOUND 所调用的API不存在
500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务
该文档未解决您的疑问?查看常见问题