# 描述

用于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商务或技术支持团队
multifaces_tag	String	仅当return_multifaces_tag参数为1时，返回此字段 0：单人脸 1：多人脸
multifaces_image	String	如果multifaces_tag=1，则返回一张包含多人脸的图像，以jpg编码并用base64字符串返回；如果multifaces_tag=0，则返回空
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客服或商务	否