checkresult

概览

  • API URL:/api/v1a/zoloz/facecapture/checkresult
  • API 描述:该接口用于获取人脸采集的结果。

说明:该接口支持重复调用,即符合幂等性。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32

-

业务ID,业务的唯一标识,用于追踪业务。例如,商户业务相关数据库中的序列号。

说明:ZOLOZ服务器不检查该字段的值是否唯一。为了更便捷地追踪业务,建议开启商户服务器,并确保业务ID的唯一性。

"2017839040588699"

transactionId

String

64

-

事务ID,由ZOLOZ Face Capture initialize API在初始化人脸采集时的响应消息中返回。

"G006600016CN20190114000000009572520355"

isReturnImage

String

1

N

是否在响应中返回图片数据。取值如下:

  • Y:在响应中返回图片数据。
  • N:不在响应中返回图片数据。

"Y"

extraImageControlList

List<String>

-

[]

指定需要返回的额外的图片。支持的图片类型如下:

  • FACE_EYE_CLOSE:返回闭眼的人脸图片。
  • CROPPED_FACE:返回裁剪后的人脸图片。

说明

  • 当isReturnImage为Y时,该参数才生效。
  • FACE_EYE_CLOSE仅在特定serviceLevel(例如FACECAPTURE0010)下生效,请参见initialize API
  • CROPPED_FACE仅在initialize API中指定cropFaceImage参数为Y时生效,请参见initialize API

["FACE_EYE_CLOSE"]

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

API请求结果,包含结果状态、结果码和结果消息。

{

"resultCode": "SUCCESS", "resultMessage": "Success", "resultStatus": "S"

}

extInfo

ExtInfo

人脸采集的详细信息。详细信息,请参见ExtInfo

说明:当result.resultCode的值为SUCCESS时,才返回该字段。

{

"imageContent": "base64string.....", "faceAttack": false, "rect": { "top": 233, "left": 165, "bottom": 479, "right": 410 }, "quality": 97.61517973846627 }

faceCaptureResult

String

人脸采集总结果。人脸采集总结果将以Success、Failure、VoidTimeout、InProcess的形式返回。

  • Success:人脸质量总结果及活体检测均通过。
  • Failure:本次认证存在较高风险,建议拒绝。人脸质量总结果或人脸活体检测不通过。
  • VoidTimeout:未获得人脸采集结果,人脸采集超时。
  • InProcess:未获得人脸采集结果,正在采集中。

"Success"

ExtInfo字段说明

字段名称

数据类型

必须返回

描述

示例值

imageContent

String

采集到的人脸图片,采用Base64编码格式。

"base64string....."

faceAttack

Boolean

通过人脸活体检测算法检测当前的人脸采集图片是否属于假脸攻击。

  • true:假脸攻击。
  • false:非假脸攻击。

说明:当qualityPassed的值为false时,该字段的返回值为null。

false

rect

Map

人脸图片的坐标数据。

{"top": 233,

"left": 165,

"bottom": 479,

"right": 410}

quality

Double

图片质量分,取值范围0-100。

97.61517973846627

qualityPassed

Boolean

人脸质量总结果。人脸质量总结果将以true和false的形式返回。人脸质量检测支持检测多个模块,包含人脸质量分、口罩检测、遮挡检测,默认检测人脸质量分(人脸是否清晰、完整等),可根据您的实际业务需求开启更多检测项。

  • true:人脸质量分和其他检测模块均通过。当未定义其他模块时,默认检测人脸质量分。
  • false:质量检测不通过。人脸质量分或其他检测模块存在不通过项。

true

extraImages

Map<String,String>

在extraImageControlList中指定的额外需要返回的人脸图

  • Key是在extraImageControlList中指定的值。
  • Value是以Base64编码的图内容。如果未找到请求的图,则该值为“”。

{ "FACE_EYE_CLOSE": "base64string....." }

处理结果

根据请求结果执行下一步的响应动作,具体如下:

  • 当result.resultCode的值为SUCCESS时,表示调用ZOLOZ Face Capture checkresult API成功,并返回人脸采集结果。
  • 当result.resultCode的值非SUCCESS时,表示调用ZOLOZ Face Capture checkresult API失败。请检查错误码获取有关该错误的更多信息,并分析导致该错误的原因。

API通用结果码

有关通用结果码的完整列表,请参见API通用结果码

API特有结果码

Face Capture checkresult API的结果码见下表。

结果码

结果状态

描述

SUCCESS

S

API调用成功。

PROCESSING

S

正在采集人脸图片。

INVALID_ARGUMENT

F

输入参数无效。关于无效参数的详细信息,请查看返回的resultMessage。

UNUSABLE

F

ZOLOZ SDK返回的元信息未通过可用性检查,用户无法使用人脸采集功能。

SYSTEM_ERROR

F

其他内部错误。有关错误详情,请查看返回的resultMessage。

LIMIT_EXCEEDED

F

超过最大次数限制。

代码示例

请求示例

商户服务端发送的请求代码示例。

copy
{
    "bizId": "2017839040588699",
    "transactionId": "G006600016CN20190114000000009572520355",
    "isReturnImage": "Y",
    "extraImageControlList": ["FACE_EYE_CLOSE"]
}

返回示例

ZOLOZ服务器返回的响应代码示例。

copy
{
  "faceCaptureResult":"Success",
  "extInfo": {
    "imageContent": "base64string.....",
    "faceAttack": false,
    "rect": {
      "top": 233,
      "left": 165,
      "bottom": 479,
      "right": 410
    },
    "quality": 97.61517973846627,
    "qualityPassed": true,
    "extraImages": { "FACE_EYE_CLOSE": "base64string....." }
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}