接入文档
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)
|
|||||||||||||||||||||
必选 | 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”):
|
|||||||||||||||||
可选 | fail_when_ref_multiple_faces | String |
用于设置参照人脸图(image_ref[x])检测到多张人脸时,是否立即返回错误,本参数取值如下:
|
# 返回值说明
字段 | 类型 | 说明 |
---|---|---|
request_id | String | 用于区分每一次请求的唯一的字符串。此字符串可以用于后续数据反查。此字段必定返回 |
time_used | Int | 整个请求所花费的时间,单位为毫秒。此字段必定返回 |
biz_no | String | 此参数仅当调用时设置了biz_no参数才返回,但是如果设置了则即使API调用失败也返回,值与传入的biz_no保持完全一致 |
liveness | Object |
本字段结构体表示流程验证结果、活体检测的结果
本字段结构体包含两个字段:
|
result_ref[x] | Object |
本字段仅在设置了image_ref1、image_ref2或image_ref3时才返回、且只在接口被成功调用时返回。返回image_ref[x]与待验证人脸照的比对结果,分别为result_ref1、result_ref2、result_ref3。
返回综合验证分数。此字段只在接口被成功调用时返回。
|
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>有:
|
否 |
403 | CONCURRENCY_LIMIT_EXCEEDED | 并发数超过限制 | 否 |
400 | MISSING_ARGUMENTS: <key> | 缺少某个必选参数 | 否 |
400 | BAD_ARGUMENTS:<key> | 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 长度过长;不允许的输入值) | 否 |
404 | API_NOT_FOUND | 所调用的API不存在 | 否 |
500 | INTERNAL_ERROR | 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系FaceID客服或商务 | 否 |
该文档未解决您的疑问?查看常见问题