/faceset/v3/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.vietnam.accuauth.com/faceset/v3/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 | 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"
}