BWS 3 Face Recognition is in preview now!
Performs a one-to-many comparison of the uploaded face images with stored biometric templates in order to find matching persons in the database.
This method creates biometric feature vectors for all of the provided face images. To perform the comparisons, all biometric templates to compare are then fetched from the database (their digital signature is verified and they may get decrypted) according to the specified list of tags.
As the process of fetching (verification and decryption) of the biometric face templates from the database is more time-consuming than the actual comparison with the calculated feature vectors, we support bulk processing of multiple input images here. This speeds up the average comparison time a lot.
Anyway, the method has a timeout (a backend response read timeout), that may abort the call after 10 minutes.
The Search API is defined as a unary RPC:
rpc Search (FaceSearchRequest) returns (FaceSearchResponse);
message FaceSearchRequest {
repeated ImageData images = 1;
repeated string tags = 2;
bool top_matches = 3;
}
message FaceSearchResponse {
JobStatus status = 1;
repeated JobError errors = 2;
repeated ImageProperties image_properties = 3;
repeated SearchResult result = 4;
message SearchResult {
repeated TemplateMatchResult matches = 1;
}
message TemplateMatchResult {
int64 classId = 1;
double score = 2;
}
}
The FaceSearchRequest message has the fields as follows:
imagestagstop_matchestrue.
The maximum API request size is 50 MB. This is the only limitation for the number of input images.
This API requires a valid JWT in the Authorization request header and accepts an optional reference number.
| Authorization | Required Bearer authentication. Please refer to BWS API Authentication for a description of how to provide a valid JWT here. |
| Reference-Number | Optional, client specific reference number, which will be added to the BWS bookkeeping as well as to the response header. You typically use this reference to link the resulting BWS bookkeeping entries with your logs. |
On success the API returns a FaceSearchResponse message:
statuserrors may have occurred, even if the job was completed successfully.
errorsimage_propertiesresultSearchResult is created and returned in the order of the provided input images.
A SearchResult again is a sorted list (by score) of TemplateMatchResult messages containing
the identified classes or the best matches, depending on the top_matches flag in the request.
classIdscorePlease note, that this method might be a long running task, as all biometric templates need to be fetched from the database, its digital signature need to be verified and the template may need to be decrypted before it can be compared with the calculated face feature vectors. Therefore using bulk processing (sending more than one image simultaneously) and restriction to user-groups (by using tags) can speed up this method immense.
Possibly some errors might have been reported:
Beside of the success return status code OK (0), this call might also return one of the following gRPC error status codes to indicate an error:
This method might also return an HTTP error (504) in case ...:
All successful BWS gRPC calls return a response header and a response trailer containing additional information about the request:
| Response Header | |
| jobid | The Job-ID (a GUID) that has been assigned to this BWS call. |
| bws-version | The version of the BWS gRPC service. |
| reference-number | An optional reference number as provided in the request header. |
| date | The timestamp when the request has been received at the server. |
| ... | Other headers that might have been added by the server (NGINX, Kestrel, ...) that was handling the request. |
| Response Trailer | |
| response-time-ms | The timespan in milliseconds the request spent at the BWS service. |
| ... | Other trailers, like exception trailers, which are added by the gRPC framework in case an RPC exception occurred. |