Rekognition / Client / list_faces

list_faces

Rekognition.Client.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,
    UserId='string',
    FaceIds=[
        'string',
    ]
)

Parameters:

• CollectionId (string) –

  [REQUIRED]

  ID of the collection from which to list the faces.

• NextToken (string) – If the previous response was incomplete (because there is more data to retrieve), Amazon Rekognition returns a pagination token in the response. You can use this pagination token to retrieve the next set of faces.

• MaxResults (integer) – Maximum number of faces to return.

• UserId (string) – An array of user IDs to filter results with when listing faces in a collection.

• FaceIds (list) –

  An array of face IDs to filter results with when listing faces in a collection.

  • (string) –

Return type:

dict

Returns:

Response Syntax

{
    'Faces': [
        {
            'FaceId': 'string',
            'BoundingBox': {
                'Width': ...,
                'Height': ...,
                'Left': ...,
                'Top': ...
            },
            'ImageId': 'string',
            'ExternalImageId': 'string',
            'Confidence': ...,
            'IndexFacesModelVersion': 'string',
            'UserId': '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.

      • UserId (string) –

        Unique identifier assigned to the user.

  • 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.InvalidParameterException

• Rekognition.Client.exceptions.AccessDeniedException

• Rekognition.Client.exceptions.InternalServerError

• Rekognition.Client.exceptions.ThrottlingException

• Rekognition.Client.exceptions.ProvisionedThroughputExceededException

• Rekognition.Client.exceptions.InvalidPaginationTokenException

• Rekognition.Client.exceptions.ResourceNotFoundException

Examples

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': {
        '...': '...',
    },
}