Call this API to search a face.

📘
The query data is valid for 60 days.

Request Example:

curl -X POST \
  https://sg-api.advance.ai/intl/openapi/face-search/search \
  -H 'Content-Type: multipart/form-data' \
  -H 'X-ACCESS-TOKEN:{Your Access Token}' \
  --form 'faceSetId="1"' \
  --form 'faceImage=@"postman-cloud:///1ef5533f-579d-44b0-b389-7f02187f4af8"' \
  --form 'topK="20"' \
  --form 'threshold="50.0"'

Request Url

https://sg-api.advance.ai/intl/openapi/face-search/search
POST (multipart/form-data)

Parameter	Description
X-ACCESS-TOKEN	`string` Please use Token Authentication API to get your access token.

Request Parameters

Parameter	Description
faceSetId	`string` The unique id of the faceSet.
faceImage	`file` The face image in form-data.
topK	`int` [Optional] Returns the topK results of images. Default is 20.
threshold	`float` [Optional] Return the faces bigger than this threshold. The default value is 80.

Response Description

Parameter	Description
code	`enum` Status Code.
transactionId	`string` The request id, the max length is 64.
pricingStrategy	`enum` Whether the request will be charged, enum type: `FREE`, `PAY`.
message	`string` The error message used to debug.
data	`object` The searchResult.
extra	`object` Extra response info (Exception Message).

Response Code

Status Code	Message
SUCCESS	`pay` OK.
PARAMETER_ERROR	`free` Parameter error, please check your request whether has illegal parameters.
ERROR	`free` Server error.

Response.data

Parameter	Description
topK	`int` The topK search results returns by this request.
threshold	`float` The threshold used to filter the results in this request.
total	`int` The total number of faces found.
faceReferences	`list` list of face objects found. Refer to face.

Response Examples

SUCCESS

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "topK": 20,
        "threshold": 50,
        "total": 1,
        "faceReferences": [
            {
                "id": "1",
                "createdAt": "2024-08-08T03:44:11.594",
                "lastUpdatedAt": "2024-08-08T03:44:11.932",
                "deletedAt": null,
                "faceImageId": "66b43f0bd5f270562e9f0024.jpg",
                "externalReferenceId": "552dc203-1fe8-49dd-aafd-98194e374c0f",
                "idNumber": "252",
                "idCardType": "2",
                "country": "BM",
                "name": "Mrs. Margot",
                "score": 100
            }
        ]
    },
    "extra": null,
    "pricingStrategy": "PAY"
}

PARAMETER_ERROR

{
    "code": "PARAMETER_ERROR",
    "message": "FaceSet not found, id: 1",
    "data": null,
    "extra": null,
    "pricingStrategy": "FREE"
}