ZOLOZZOLOZDOCS

compare

概览

  • API URL：/api/v1/zoloz/facecompare/compare
  • API 描述：该接口用于对指定的两张人脸图片进行相似性比对，并返回比对结果。

请求参数

字段名称

数据类型

最大长度

是否必填

默认值

描述

示例值

bizId

String

32B

是

-

业务ID，业务的唯一标识，用于追踪业务。

"trans-abc-123"

userId

String

64B

否

null

商户的用户ID或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。

建议对userId字段的值进行预脱敏，例如进行哈希处理。

"userid_1234"

face1.content

String

5MB

是

-

采用Base64编码的人脸图片，该图片支持JPG、JPEG、PNG、BMP格式。

注意：

  • face1.content和face2.content两张图片的总大小不能超过5MB，如果图片过大，建议压缩后再上传，以免造成系统错误。
  • 该参数默认传入活体人脸图片，如果您传入的是证件脸图片，将无法保证识别结果的准确性。

"/9j/4AA..[omitted]..PxA="

face1.rect

String

32B

否

null

人脸坐标，格式为“左、上、宽、高”。

"123,45,234,621"

face2.content

String

5MB

是

-

采用Base64编码的人脸图片，该图片支持JPG、JPEG、PNG、BMP格式。

注意：face1.content和face2.content两张图片的总大小不能超过5MB，如果图片过大，建议压缩后再上传，以免造成系统错误。

"/9j/4AA..[omitted]..PxA="

face2.rect

String

32B

否

null

人脸坐标，格式为“左、上、宽、高”。

"123,45,234,621"

sourceOfFace2

String

32B

否

SELFIE

指定face2.content是活体人脸图片还是证件脸图片。取值如下：

说明：如果face2.content的类型与该字段传入的值不一致，会导致人脸比对结果不准确。

"SELFIE"

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

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

{

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

}

transactionId

String

是

事务ID。

说明：仅当交易进入处理阶段后系统才会返回transactionId。如果在开始处理交易之前发生错误，系统不会返回transactionId。包括但不限于以下情况：

  • 请求参数非法，例如入参格式错误或缺失必传参数。
  • 请求未能成功到达服务器，例如网络问题或网关故障。
  • 系统限流导致请求被拒绝。

"G000000005FID20200304000000000001570702"

face1ImageQualityResult

String

是

人脸1的图片质量结果。

  • PASS：合格
  • FAIL：不合格

说明：如果face1ImageQualityResult和face2ImageQualityResult中任意一个参数的结果为FAIL，则samePerson将返回false。

"PASS"

face2ImageQualityResult

String

是

人脸2的图片质量结果。

  • PASS：合格
  • FAIL：不合格

说明：如果face1ImageQualityResult和face2ImageQualityResult中任意一个参数的结果为FAIL，则samePerson将返回false。

"PASS"

score

Double

是

人脸比对分数，取值范围0-100。

88.2

samePerson

Boolean

是

人脸比对结果，算法判断两张人脸是否为同一人。

  • true：同一人。
  • false：不是同一人。

true

Result字段说明

字段名称

数据类型

必须返回

描述

示例值

resultCode

String

是

结果码。

  • INVALID_ARGUMENT：输入参数无效。
    • bizId为null或空字符串。
    • livenessDetectMode的值不是NONE或NORMAL。
  • UNABLE_GET_IMAGE：无法获取图片。
    • 人脸图片Base64字符串为null或空字符串或损坏。
    • 人脸图片不是JPG格式。
    • 图片中未检测到人脸。
  • SUCCESS：无论两张人脸是否为同一人，都将成功返回比对结果。
  • SYSTEM_ERROR：其他内部错误。

"SUCCESS"

resultStatus

String

是

结果状态。

"S"

resultMessage

String

是

结果信息。

"success"

代码示例

请求示例

copy
POST /api/v1/zoloz/facecompare/compare HTTP/1.1
Content-Type: application/json; charset=UTF-8
Client-Id: 5X67656YXXXXXX
Request-Time: 2019-04-04T12:08:56+05:30
Signature: algorithm=RSA256, signature=xxxxxxxxxxxx

{
  "bizId": "trans-test-1234",
  "userId":"userid_1234",
  "face1": {
    "content": "/9j/4AA..[omitted]..PxA=",
    "rect": "234,54,22,123"
  },
  "face2": {
    "content": "/9j/4AA..[omitted]..tvq=",
    "rect": "234,432,34,22"
  },
  "sourceOfFace2": "SELFIE"
}

返回示例

copy
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Response-Time: 2019-11-19T21:56:15-0800
Signature: algorithm=RSA256, signature=xxxxxxxxxxxxxxxxxx

{
  "transactionId": "G000000005FID20200304000000000001570702",
  "face1ImageQualityResult":"PASS",
  "face2ImageQualityResult":"PASS",
  "score": 88.2,
  "samePerson": true,
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success"
  }
}