list_faces(**kwargs)¶Returns metadata for faces in the specified collection. This metadata includes information such as the bounding box coordinates, the confidence (that the bounding box contains a face), and face ID. For an example, see Listing Faces in a Collection in the Amazon Rekognition Developer Guide.
This operation requires permissions to perform the rekognition:ListFaces action.
See also: AWS API Documentation
Request Syntax
response = client.list_faces(
CollectionId='string',
NextToken='string',
MaxResults=123
)
[REQUIRED]
ID of the collection from which to list the faces.
dict
Response Syntax
{
'Faces': [
{
'FaceId': 'string',
'BoundingBox': {
'Width': ...,
'Height': ...,
'Left': ...,
'Top': ...
},
'ImageId': 'string',
'ExternalImageId': 'string',
'Confidence': ...,
'IndexFacesModelVersion': 'string'
},
],
'NextToken': 'string',
'FaceModelVersion': 'string'
}
Response Structure
(dict) --
Faces (list) --
An array of Face objects.
(dict) --
Describes the face properties such as the bounding box, face ID, image ID of the input image, and external image ID that you assigned.
FaceId (string) --
Unique identifier that Amazon Rekognition assigns to the face.
BoundingBox (dict) --
Bounding box of the face.
Width (float) --
Width of the bounding box as a ratio of the overall image width.
Height (float) --
Height of the bounding box as a ratio of the overall image height.
Left (float) --
Left coordinate of the bounding box as a ratio of overall image width.
Top (float) --
Top coordinate of the bounding box as a ratio of overall image height.
ImageId (string) --
Unique identifier that Amazon Rekognition assigns to the input image.
ExternalImageId (string) --
Identifier that you assign to all the faces in the input image.
Confidence (float) --
Confidence level that the bounding box contains a face (and not a different object such as a tree).
IndexFacesModelVersion (string) --
The version of the face detect and storage model that was used when indexing the face vector.
NextToken (string) --
If the response is truncated, Amazon Rekognition returns this token that you can use in the subsequent request to retrieve the next set of faces.
FaceModelVersion (string) --
Version number of the face detection model associated with the input collection ( CollectionId ).
Exceptions
Rekognition.Client.exceptions.InvalidParameterExceptionRekognition.Client.exceptions.AccessDeniedExceptionRekognition.Client.exceptions.InternalServerErrorRekognition.Client.exceptions.ThrottlingExceptionRekognition.Client.exceptions.ProvisionedThroughputExceededExceptionRekognition.Client.exceptions.InvalidPaginationTokenExceptionRekognition.Client.exceptions.ResourceNotFoundExceptionExamples
This operation lists the faces in a Rekognition collection.
response = client.list_faces(
CollectionId='myphotos',
MaxResults=20,
)
print(response)
Expected Output:
{
'Faces': [
{
'BoundingBox': {
'Height': 0.18000000715255737,
'Left': 0.5555559992790222,
'Top': 0.336667001247406,
'Width': 0.23999999463558197,
},
'Confidence': 100,
'FaceId': '1c62e8b5-69a7-5b7d-b3cd-db4338a8a7e7',
'ImageId': '147fdf82-7a71-52cf-819b-e786c7b9746e',
},
{
'BoundingBox': {
'Height': 0.16555599868297577,
'Left': 0.30963000655174255,
'Top': 0.7066670060157776,
'Width': 0.22074100375175476,
},
'Confidence': 100,
'FaceId': '29a75abe-397b-5101-ba4f-706783b2246c',
'ImageId': '147fdf82-7a71-52cf-819b-e786c7b9746e',
},
{
'BoundingBox': {
'Height': 0.3234420120716095,
'Left': 0.3233329951763153,
'Top': 0.5,
'Width': 0.24222199618816376,
},
'Confidence': 99.99829864501953,
'FaceId': '38271d79-7bc2-5efb-b752-398a8d575b85',
'ImageId': 'd5631190-d039-54e4-b267-abd22c8647c5',
},
{
'BoundingBox': {
'Height': 0.03555560111999512,
'Left': 0.37388700246810913,
'Top': 0.2477779984474182,
'Width': 0.04747769981622696,
},
'Confidence': 99.99210357666016,
'FaceId': '3b01bef0-c883-5654-ba42-d5ad28b720b3',
'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
},
{
'BoundingBox': {
'Height': 0.05333330109715462,
'Left': 0.2937690019607544,
'Top': 0.35666701197624207,
'Width': 0.07121659815311432,
},
'Confidence': 99.99919891357422,
'FaceId': '4839a608-49d0-566c-8301-509d71b534d1',
'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
},
{
'BoundingBox': {
'Height': 0.3249259889125824,
'Left': 0.5155559778213501,
'Top': 0.1513350009918213,
'Width': 0.24333299696445465,
},
'Confidence': 99.99949645996094,
'FaceId': '70008e50-75e4-55d0-8e80-363fb73b3a14',
'ImageId': 'd5631190-d039-54e4-b267-abd22c8647c5',
},
{
'BoundingBox': {
'Height': 0.03777780011296272,
'Left': 0.7002969980239868,
'Top': 0.18777799606323242,
'Width': 0.05044509842991829,
},
'Confidence': 99.92639923095703,
'FaceId': '7f5f88ed-d684-5a88-b0df-01e4a521552b',
'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
},
{
'BoundingBox': {
'Height': 0.05555560067296028,
'Left': 0.13946600258350372,
'Top': 0.46333301067352295,
'Width': 0.07270029932260513,
},
'Confidence': 99.99469757080078,
'FaceId': '895b4e2c-81de-5902-a4bd-d1792bda00b2',
'ImageId': '812d9f04-86f9-54fc-9275-8d0dcbcb6784',
},
{
'BoundingBox': {
'Height': 0.3259260058403015,
'Left': 0.5144439935684204,
'Top': 0.15111100673675537,
'Width': 0.24444399774074554,
},
'Confidence': 99.99949645996094,
'FaceId': '8be04dba-4e58-520d-850e-9eae4af70eb2',
'ImageId': '465f4e93-763e-51d0-b030-b9667a2d94b1',
},
{
'BoundingBox': {
'Height': 0.18888899683952332,
'Left': 0.3783380091190338,
'Top': 0.2355560064315796,
'Width': 0.25222599506378174,
},
'Confidence': 99.9999008178711,
'FaceId': '908544ad-edc3-59df-8faf-6a87cc256cf5',
'ImageId': '3c731605-d772-541a-a5e7-0375dbc68a07',
},
{
'BoundingBox': {
'Height': 0.33481499552726746,
'Left': 0.31888899207115173,
'Top': 0.49333301186561584,
'Width': 0.25,
},
'Confidence': 99.99909973144531,
'FaceId': 'ff43d742-0c13-5d16-a3e8-03d3f58e980b',
'ImageId': '465f4e93-763e-51d0-b030-b9667a2d94b1',
},
],
'ResponseMetadata': {
'...': '...',
},
}