Amazon Rekognition
Developer Guide

Step 4: Getting Started Using the API

In this section you use the Amazon Rekognition API operations to detect labels and faces in an image. You also explore the CompareFaces API operation. These are the non-storage API operations where Amazon Rekognition doesn't persist any information discovered by the operation. Amazon Rekognition only detects labels and faces, and it returns information in response. For more information, see Amazon Rekognition: How It Works. Like all other Amazon Rekognition API operations, no input image bytes are persisted by non-storage API operations.

Using the AWS SDK or HTTP to Call Amazon Rekognition API Operations

You can call Amazon Rekognition API operations using either the AWS SDK or directly by using HTTP. Unless you have a good reason not to, you should always use the AWS SDK. The Java examples in this section use the AWS SDK. A Java project file is not provided, but you can use the AWS Toolkit for Eclipse to develop AWS applications using Java.

The API Reference in this guide covers calling Amazon Rekognition operations using HTTP. For Java reference information, see AWS SDK for Java.

The Amazon Rekognition service endpoints you can use are documented at AWS Regions and Endpoints.

When calling Amazon Rekognition with HTTP, use POST HTTP operations.

Formatting the AWS CLI Examples

The AWS CLI examples are formatted for the Linux operating system. To use the samples with Microsoft Windows, you will need to change the JSON formatting of the --image parameter and change the line breaks from backslashes (\) to carets(^). For more information about JSON formatting, see Specifying Parameter Values for the AWS Command Line Interface. The following is an example AWS CLI command formatted for Microsoft Windows.

aws rekognition detect-labels ^ --image "{\"S3Object\":{\"Bucket\":\"photo-collection\",\"Name\":\"photo.jpg\"}}" ^ --region us-west-2

You can also provide a shorthand version of the JSON that works on both Microsoft Windows and Linux.

aws rekognition detect-labels --image "S3Object={Bucket=photo-collection,Name=photo.jpg}" --region us-west-2

For more information, see Using Shorthand Syntax with the AWS Command Line Interface.

Working with Images

You need sample images (JPEG or PNG) that you can provide as input to Amazon Rekognition operations.

You pass image bytes to an Amazon Rekognition operation as part of the call or you reference an existing S3 object. If you use HTTP and pass the image bytes as part of an Amazon Rekognition operation, the image bytes must be a base64-encoded string. If you use the AWS SDK and pass image bytes as part of the API operation call, the need to base64-encode the image bytes depends on the language you use. For more information, see Example 4: Supplying Image Bytes to Amazon Rekognition Operations.

If you use the AWS CLI to call Amazon Rekognition operations, passing image bytes as part of the call is not supported. You must first upload the image to an Amazon S3 bucket and then call the operation referencing the uploaded image.

To ensure the lowest possible latency, the region for the S3 bucket containing your images must match the region you use for Amazon Rekognition API operations.

Recommendations for Facial Recognition Input Images

Whilst Amazon Rekognition works across a variety of image conditions and sizes, we recommend the following guidelines when choosing reference photos for facial recognition:

  • Have a front-facing face.

  • Have flat lighting on the face, as opposed to varying shades such as shadows.

  • Have sufficient contrast with the background. A high-contrast monochrome background works well.

  • Be sufficiently large. Amazon Rekognition can detect faces as small as 40x40 pixels in an HD resolution image (1980x1080). Higher resolution images will need a larger minimum face size.

  • Be bright and sharp. You can use DetectFaces to determine the brightness and sharpness of a face.

  • Avoid occlusions such as head-bands or masks.

Correcting Image Orientation

In several Rekognition API operations, the orientation of an analyzed image is returned. For example, the DetectFaces API operation returns orientation information about the source image in the OrientationCorrection field. Knowing image orientation is important as it allows you to reorient images for display. Rekognition API operations that analyze faces also return bounding boxes for the location of faces within an image. You can use bounding boxes to display a box around a face on an image. The bounding box coordinates returned are affected by image orientation and you may need to translate bounding box coordinates to correctly display a box around a face. For more information, see Example 5: Getting Image Orientation and Bounding Box Coordinates.