compare

2022-05-09 03:03

概览

API 名称：ZOLOZ SaaS Face compare API。
API URL：/api/v1/zoloz/facecompare/compare
API 描述：对指定的两张人脸图片进行相似性对比和活体检测，并返回对比结果及活体检测结果。

版本说明

日期	版本号	发布说明
2019.11.29	1.0.1	移除活体检测。
2019.11.25	1.0.0	首次发布

请求

字段说明

字段名称	类型	最大长度	必填	默认值	取值范围	描述	示例值
bizId	string	32B	是		不能为 null 或空字符串。	出于追踪目的的业务 ID。	"trans-abc-123"
face1.content	string	1MB	是		不能为 null 或空字符串。	以 Base64 编码的 JPG 格式的人脸图像。	"/9j/4AA..[omitted]..PxA="
face1.rect	string	32B	否	null		格式为“左，上，宽，高”的人脸坐标。	"123,45,234,621"
face2.content	string	1MB	是		不能为 null 或空字符串。	以 Base64 编码的 JPG 格式的人脸图像。	"/9j/4AA..[omitted]..PxA="
face2.rect	string	32B	否	null		格式为“左，上，宽，高”的人脸坐标。	"123,45,234,621"

请求示例

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",
  "face1": {
    "content": "/9j/4AA..[omitted]..PxA=",
    "rect": "234,54,22,123"
  },
  "face2": {
    "content": "/9j/4AA..[omitted]..tvq=",
    "rect": "234,432,34,22"
  }
}

响应

字段说明

字段名称	类型	必填	取值范围	描述	示例值
transactionId	string	是		事务 ID	"G000000005FID20200304000000000001570702"
score	double	是	(0.0, 100.0)	人脸对比分数	88.2
samePerson	boolean	是	true, false	face1 和 face2 是否为同一个人	true
result.resultCode	string	是		结果码	"SUCCESS"
result.resultStatus	string	是		结果状态	"S"
result.resultMessage	string	否		结果信息	"success"

resultCode 业务层面的取值范围：

结果码	描述
PARAM_ILLEGAL	bizId 的值为 null 或空字符串。 livenessDetectMode 的值不是 NONE 或 NORMAL。
UNABLE_GET_IMAGE	人脸图片 base64 字符串为 null 或空字符串或损坏。人脸图片不是 jpg 格式。图像中未检测到人脸。
SUCCESS	成功返回比对结果，该结果码不能表示 face1 和 face2 是同一个人。
SYSTEM_ERROR	其他内部错误。

响应示例

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",
  "score": 88.2,
  "samePerson": true,
  "result": {
    "resultCode":"SUCCESS",
    "resultStatus":"S",
    "resultMessage":"success",
    "transactionId": "xxxxxx"
  }
}

附录

CommonResult

描述：表示 API 调用状态的统一数据结构。

字段说明

字段名称	类型	必填	取值范围	描述	示例值
resultCode	string	是		结果码	"SUCCESS"
resultCode	string	是	"S": successful "F": failed	结果状态	"S"
resultMessage	string	是		结果说明	"success"

resultCode 业务层面的取值范围：

结果码	描述
PARAM_ILLEGAL	bizId 的值为 null 或空字符串。 livenessDetectMode 的值不是 NONE 或 NORMAL。
UNABLE_GET_IMAGE	人脸图片 base64 字符串为 null 或空字符串或损坏。人脸图片不是 jpg 格式。图像中未检测到人脸。
SUCCESS	成功返回比对结果，该结果码不能表示 face1 和 face2 是同一个人。
SYSTEM_ERROR	其他内部错误。

RequestFaceImage

描述：带有人脸图像信息的数据结构。

字段说明

字段名称	类型	必填	默认值	描述	示例值
content	string	是		以 Base64 编码的 JPG 格式的人脸图像。	"/9j/4AA..[omitted]..PxA="
rect	string	否	null	格式为“左，上，宽，高”的人脸坐标。	"112,234,455,89"