AWS API Changes

2026/09/25 - Amazon Rekognition - 1 updated api methods

Changes This release adds support for Feedback and Metadata in the GetFaceLivenessSessionResults response. Feedback returns codes explaining why a Face Liveness check produced its result. Metadata includes the client SDK type.

GetFaceLivenessSessionResults (updated)

Link ¶
Changes (response)

{'Feedback': [{'Code': 'FACE_NOT_VISIBLE | FACE_OBSTRUCTION_DETECTED | '
                       'LOW_VIDEO_QUALITY_DETECTED | FACE_NOT_ALIGNED | '
                       'EYES_CLOSED_DETECTED | LOW_LIGHTING_DETECTED | '
                       'HIGH_LIGHTING_DETECTED',
               'Message': 'string'}],
 'Metadata': {'SDKType': 'string'}}

Retrieves the results of a specific Face Liveness session. It requires the sessionId as input, which was created using CreateFaceLivenessSession. Returns the corresponding Face Liveness confidence score, a reference image that includes a face bounding box, and audit images that also contain face bounding boxes. The Face Liveness confidence score ranges from 0 to 100.

The number of audit images returned by GetFaceLivenessSessionResults is defined by the AuditImagesLimit paramater when calling CreateFaceLivenessSession. Reference images are always returned when possible.

For a session that has completed, the response can also include a Feedback list describing conditions that were detected in the selfie-video, such as low lighting or an obstructed face, and Metadata about the client that streamed the session.

See also: AWS API Documentation

Request Syntax

client.get_face_liveness_session_results(
    SessionId='string'
)

type SessionId:

string

param SessionId:

[REQUIRED]

A unique 128-bit UUID. This is used to uniquely identify the session and also acts as an idempotency token for all operations associated with the session.

rtype:

dict

returns:

Response Syntax

{
    'SessionId': 'string',
    'Status': 'CREATED'|'IN_PROGRESS'|'SUCCEEDED'|'FAILED'|'EXPIRED',
    'Confidence': ...,
    'ReferenceImage': {
        'Bytes': b'bytes',
        'S3Object': {
            'Bucket': 'string',
            'Name': 'string',
            'Version': 'string'
        },
        'BoundingBox': {
            'Width': ...,
            'Height': ...,
            'Left': ...,
            'Top': ...
        }
    },
    'AuditImages': [
        {
            'Bytes': b'bytes',
            'S3Object': {
                'Bucket': 'string',
                'Name': 'string',
                'Version': 'string'
            },
            'BoundingBox': {
                'Width': ...,
                'Height': ...,
                'Left': ...,
                'Top': ...
            }
        },
    ],
    'Challenge': {
        'Type': 'FaceMovementAndLightChallenge'|'FaceMovementChallenge',
        'Version': 'string'
    },
    'Feedback': [
        {
            'Code': 'FACE_NOT_VISIBLE'|'FACE_OBSTRUCTION_DETECTED'|'LOW_VIDEO_QUALITY_DETECTED'|'FACE_NOT_ALIGNED'|'EYES_CLOSED_DETECTED'|'LOW_LIGHTING_DETECTED'|'HIGH_LIGHTING_DETECTED',
            'Message': 'string'
        },
    ],
    'Metadata': {
        'SDKType': 'string'
    }
}

Response Structure

(dict) --
- SessionId (string) --
  
  The sessionId for which this request was called.
- Status (string) --
  
  Represents a status corresponding to the state of the session. Possible statuses are: CREATED, IN_PROGRESS, SUCCEEDED, FAILED, EXPIRED.
- Confidence (float) --
  
  Probabalistic confidence score for if the person in the given video was live, represented as a float value between 0 to 100.
- ReferenceImage (dict) --
  
  A high-quality image from the Face Liveness video that can be used for face comparison or search. It includes a bounding box of the face and the Base64-encoded bytes that return an image. If the CreateFaceLivenessSession request included an OutputConfig argument, the image will be uploaded to an S3Object specified in the output configuration. In case the reference image is not returned, it's recommended to retry the Liveness check.
  - Bytes (bytes) --
    
    The Base64-encoded bytes representing an image selected from the Face Liveness video and returned for audit purposes.
  - S3Object (dict) --
    
    Provides the S3 bucket name and object name.
    
    The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.
    
    For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see How Amazon Rekognition works with IAM in the Amazon Rekognition Developer Guide.
    - Bucket (string) --
      
      Name of the S3 bucket.
    - Name (string) --
      
      S3 object key name.
    - Version (string) --
      
      If the bucket is versioning enabled, you can specify the object version.
  - BoundingBox (dict) --
    
    Identifies the bounding box around the label, face, text, object of interest, or personal protective equipment. The left (x-coordinate) and top (y-coordinate) are coordinates representing the top and left sides of the bounding box. Note that the upper-left corner of the image is the origin (0,0).
    
    The top and left values returned are ratios of the overall image size. For example, if the input image is 700x200 pixels, and the top-left coordinate of the bounding box is 350x50 pixels, the API returns a left value of 0.5 (350/700) and a top value of 0.25 (50/200).
    
    The width and height values represent the dimensions of the bounding box as a ratio of the overall image dimension. For example, if the input image is 700x200 pixels, and the bounding box width is 70 pixels, the width returned is 0.1.
    
    Note
    
    The bounding box coordinates can have negative values. For example, if Amazon Rekognition is able to detect a face that is at the image edge and is only partially visible, the service can return coordinates that are outside the image bounds and, depending on the image edge, you might get negative values or values greater than 1 for the left or top values.
    - 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.
- AuditImages (list) --
  
  A set of images from the Face Liveness video that can be used for audit purposes. It includes a bounding box of the face and the Base64-encoded bytes that return an image. If the CreateFaceLivenessSession request included an OutputConfig argument, the image will be uploaded to an S3Object specified in the output configuration. If no Amazon S3 bucket is defined, raw bytes are sent instead.
  - (dict) --
    
    An image that is picked from the Face Liveness video and returned for audit trail purposes, returned as Base64-encoded bytes.
    - Bytes (bytes) --
      
      The Base64-encoded bytes representing an image selected from the Face Liveness video and returned for audit purposes.
    - S3Object (dict) --
      
      Provides the S3 bucket name and object name.
      
      The region for the S3 bucket containing the S3 object must match the region you use for Amazon Rekognition operations.
      
      For Amazon Rekognition to process an S3 object, the user must have permission to access the S3 object. For more information, see How Amazon Rekognition works with IAM in the Amazon Rekognition Developer Guide.
      - Bucket (string) --
        
        Name of the S3 bucket.
      - Name (string) --
        
        S3 object key name.
      - Version (string) --
        
        If the bucket is versioning enabled, you can specify the object version.
    - BoundingBox (dict) --
      
      Identifies the bounding box around the label, face, text, object of interest, or personal protective equipment. The left (x-coordinate) and top (y-coordinate) are coordinates representing the top and left sides of the bounding box. Note that the upper-left corner of the image is the origin (0,0).
      
      The top and left values returned are ratios of the overall image size. For example, if the input image is 700x200 pixels, and the top-left coordinate of the bounding box is 350x50 pixels, the API returns a left value of 0.5 (350/700) and a top value of 0.25 (50/200).
      
      The width and height values represent the dimensions of the bounding box as a ratio of the overall image dimension. For example, if the input image is 700x200 pixels, and the bounding box width is 70 pixels, the width returned is 0.1.
      
      Note
      
      The bounding box coordinates can have negative values. For example, if Amazon Rekognition is able to detect a face that is at the image edge and is only partially visible, the service can return coordinates that are outside the image bounds and, depending on the image edge, you might get negative values or values greater than 1 for the left or top values.
      - 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.
- Challenge (dict) --
  
  Contains information regarding the challenge type used for the Face Liveness check.
  - Type (string) --
    
    The type of the challenge being used for the Face Liveness session.
  - Version (string) --
    
    The version of the challenge being used for the Face Liveness session.
- Feedback (list) --
  
  A list of conditions that were detected in the Face Liveness video and that contributed to the returned Confidence score. Each item contains a code and a human-readable message. Feedback is returned only for sessions with a Status of SUCCEEDED, and the list is empty when no such conditions were detected.
  - (dict) --
    
    Describes a condition that was detected in the Face Liveness video and that contributed to the confidence score returned for the session.
    - Code (string) --
      
      A code identifying the condition that was detected during the Face Liveness session.
    - Message (string) --
      
      A human-readable description of the detected condition, suitable for displaying to an end user before they retry a Face Liveness check. Use Code rather than this message for programmatic decisions, because the message text can change.
- Metadata (dict) --
  
  Metadata about the client that streamed the video for the Face Liveness session.
  - SDKType (string) --
    
    The type of SDK that was used to stream the video for the Face Liveness session.
    
    Note
    
    This value is self-reported by the client that streamed the session, and Amazon Rekognition doesn't verify it. Don't rely on it for authentication, authorization, or any other security decision.