For a given input image, first detects the largest face in the image, and then searches the specified collection for matching faces. The operation compares the features of the input face with faces in the specified collection.
To search for all faces in an input image, you might first call the API, and then use the face IDs returned in subsequent calls to the API.
You can also call the DetectFaces API and use the bounding boxes in the response to make face crops, which then you can pass in to the SearchFacesByImage API.
The response returns an array of faces that match, ordered by similarity score with the highest similarity first. More specifically, it is an array of metadata for each face match found. Along with the metadata, the response also includes a similarity indicating how similar the face is to the input face. In the response, the API also returns the bounding box (and a confidence level that the bounding box contains a face) of the face that Rekognition used for the input image.
For an example, see example3.
This operation requires permissions to perform the rekognition:SearchFacesByImage action.
/// You are not authorized to perform the action.
///
/// The input image size exceeds the allowed limit. For more information, see
limits.
///
/// Amazon Rekognition experienced a service issue. Try your call again.
///
/// The provided image format is not supported.
///
/// Input parameter violated a constraint. Validate your parameter before calling the
/// API again.
///
/// Amazon Rekognition is unable to access the S3 object specified in the request.
///
/// The number of requests exceeded your throughput limit. If you want to increase this
/// limit, contact Amazon Rekognition.
///
/// Collection specified in the request is not found.
///
/// Amazon Rekognition is temporarily unable to process the request. Try your call again.
///
