/faceset/v2/search_face
1.API Specification
2.Request Params
3.Response Params
4.Error Codes
5.Sample
1.API Specification
This API is used to search similar faces from face set.
Image spec
1. Format: JPG(JPEG), PNG
2. Between 128*128 and 6000*6000 (pixels), Recommended resolution: 1280*1280
3. File size: no larger than 5 MB
Request Method
POST
Request URL
https://cloudapi.peru.accuauth.com/faceset/v2/search_face
Debugging Tool
2.Request Params
2.1 Request Header
| Parameter | Type | Required | Description |
|---|---|---|---|
| X-DF-API-ID | string | Yes | For API credentials，Please visit API Request |
| X-DF-API-SECRET | string | Yes | For API credentials，Please visit API Request |
2.2 Request Body
| Fields | Type | Description | |
|---|---|---|---|
| required | name | string | Name of face set |
| optional | file | file | Binary data of the face image |
| optional | image_base64 | string | Base64 encoded data of the face image |
| optional | threshold | float | Customized face similar threshold, the default value is 0.8, see Recommended threshold |
| optional | start_time | int | The oldest or earliest timestamp(the number of seconds that have elapsed since January 1, 1970) from which the face will be searched, The default start timestamp is the current time minus 6 months；Currently we support searching faces up to 6 months old. |
| optional | topN | int | The maximum number of faces returned by the API, the default value is 1, the maximum value is 10 |
Either parameter
fileorimage_base64must be provided as a request parameter.
2.2.1 Recommended threshold
| Threshold | False detection |
|---|---|
| 0.65 | very little |
| 0.7 | rarely |
3.Response Params
| Fields | Type | Description |
|---|---|---|
| request_id | string | Unique id of each request |
| status | string | Response status. OK means "request success", other means "request failure"，see Error Codes |
| result | array | The search result, include up to 10 most similar faces |
3.1 Elements in result
| Fields | Type | Description |
|---|---|---|
| person_id | int | The person id |
| face_id | int | The face id |
| score | float | The similarity score, [threshold, 1] range, the higher the score the more likely that being the same person. |
| create_time | int | Timestamp of face creation |
Reponse Syntax：
{
"status": "OK",
"request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
"result": [
{
"person_id": 1,
"face_id": 435449455488008194,
"score": 0.985,
"create_time": 1669077702
}
]
}
4.Error Codes
| Code | Status Field |
Description |
|---|---|---|
400 |
INVALID_ARGUMENT | Request parameter is invalid |
400 |
QUERY_FAILED | Face set error |
400 |
DOWNLOAD_ERROR | Image download failed |
401 |
UNAUTHORIZED | Anauthorized or access is denied |
401 |
KEY_EXPIRED | Your API ID has expired |
403 |
NO_PERMISSION | You are not authorized to use this API |
403 |
OUT_OF_QUOTA | API calls quota exceeded |
403 |
RATE_LIMIT_EXCEEDED | API request frequency exceeds the limit |
404 |
NOT_FOUND | Requested API cannot be found |
500 |
INTERNAL_ERROR | Internal server error |
Reponse Syntax:
{
"status": "QUERY_FAILED",
"reason": "no result",
"request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}