compare

2024-09-14 09:05

Overview

API Name: ZOLOZ SaaS Face Compare API

API URL: /api/v1/zoloz/facecompare/compare

API Description: Providing the capability of similarity comparison between two given faces.

Version

Date	Version	Release Notes
25 November, 2019	1.0.0	The first published version.
29 November, 2019	1.0.1	remove liveness detection.

Request

Fields Specification

Name	Type	Max Length	Mandatory	Default Value	Value Range	Description	Sample Value
bizId	string	32B	true		not null and not empty string	Unique business ID for tracing purposes.	"trans-abc-123"
userId	string	64B	false	null		Merchant user ID, or other identifiers that can be used to identify a specific user. For example, mobile phone number, email address and so on. It is strongly recommended to pre-desensitize the value of the userId field; for example, by hashing the value.	"userid_1234"
face1.content	string	5MB	true		not null and not empty string	Base64 encoded face image which supports JPG/JPEG/PNG/BMP formats. Note: Pass selfie image for this parameter. Accuracy of the recognition result cannot be guaranteed when a document with face image is passed.	"/9j/4AA..[omitted]..PxA="
face1.rect	string	32B	false	null		Face coordinates in "left,top,width,height" format.	"123,45,234,621"
face2.content	string	5MB	true		not null and not empty string	Base64 encoded face image which supports JPG/JPEG/PNG/BMP formats.	"/9j/4AA..[omitted]..PxA="
face2.rect	string	32B	false	null		Face coordinates in "left,top,width,height" format.	"123,45,234,621"
sourceOfFace2	string	32B	false	SELFIE	`SELFIE` or `00000001007` or valid `docType` Note: For the specific valid `docType`, please refer to Document types supported and OCR results returned.	Specify whether `face2.content` is a selfie image or a face image from a document. `SELFIE`: a selfie image valid `docType`: a face image from a document which matches `docType` `00000001007`: a face image from a document not supported by ZOLOZ now Note: If the type of `face2.content` does not match the value of this field, the matching result will be inaccurate.	"SELFIE"

Note：Currently, the total size of the two images, face1.content and face2.content, must not surpass 5MB. Should it exceed this limit, please compress the images prior to uploading them in order to prevent system errors.

Request Sample

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"
}

Response

Fields Specification

Name	Type	Mandatory	Value Range	Description	Sample Value
transactionId	string	true		transaction id	"G000000005FID20200304000000000001570702"
score	double	true	(0.0, 100.0)	face comparison score	88.2
samePerson	boolean	true	true, false	are the two faces the same person based on algorithm	true
result.resultCode	string	true		result code	"SUCCESS"
result.resultStatus	string	true		result status	"S"
result.resultMessage	string	true		result message	"success"

The value range of "resultCode" at business level:

resultCode	Description
PARAM_ILLEGAL	bizId is null or empty string; livenessDetectMode doesn't equal to "NONE" or "NORMAL";
UNABLE_GET_IMAGE	the base64 string of face image is null or empty string or damaged; the face image is not in jpg format; no face detected in image;
SUCCESS	the comparison result is successfully returned, regardless whether face1 and face2 indicate the same person;
SYSTEM_ERROR	other internal errors;

Response Sample

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"
  }
}

Appendix

CommonResult Model

Description: A unified data structure that indicates the status of API invocation.

Fields Specification:

Name	Type	Mandatory	Value Range	Description	Sample Value
resultCode	string	true		result code	"SUCCESS"
resultStatus	string	true	"S": successful "F": failed	result status	"S"
resultMessage	string	true		result description	"success"

The value range of "resultCode" at business level:

resultCode	Description
INVALID_ARGUMENT	bizId is null or empty string; livenessDetectMode doesn't equal to "NONE" or "NORMAL";
UNABLE_GET_IMAGE	the base64 string of face image is null or empty string or damaged; the face image is not in jpg format; no face detected in image;
SUCCESS	the comparison result is successfully returned, regardless whether face1 and face2 indicate the same person;
SYSTEM_ERROR	other internal errors;

RequestFaceImage Model

Description: A data structure that represents an image with face.

Fields Specification:

Name	Type	Mandatory	Default Value	Value Range	Description	Sample Value
content	string	true			base 64 string of face image in jpg format.	"/9j/4AA..[omitted]..PxA="
rect	string	false	null		face coordinates in format "left,top,width,height"	"112,234,455,89"