Face Compare API

2021-04-15 13:47

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	business unique ID for tracing purpose	"trans-abc-123"
face1.content	string	1MB	true		not null and not empty string	base 64 string of face image in jpg format.	"/9j/4AA..[omitted]..PxA="
face1.rect	string	32B	false	null		face coordinates in format "left,top,width,height"	"123,45,234,621"
face2.content	string	1MB	true		not null and not empty string	base 64 string of face image in jpg format.	"/9j/4AA..[omitted]..PxA="
face2.rect	string	32B	false	null		face coordinates in format "left,top,width,height"	"123,45,234,621"

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

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
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;

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"

ZOLOZ Team