• Step 4: Getting started using the Amazon Rekognition console (p. 15)
Step 1: Set up an AWS account and create an IAM user
Before you use Amazon Rekognition for the first time, complete the following tasks:
1.Sign up for AWS (p. 11) 2.Create an IAM user (p. 12)
Sign up for AWS
When you sign up for Amazon Web Services (AWS), your AWS account is automatically signed up for all services in AWS, including Amazon Rekognition. You're charged only for the services that you use.
With Amazon Rekognition, you pay only for the resources you use. If you're a new AWS customer, you can get started with Amazon Rekognition for free. For more information, see AWS Free Usage Tier.
If you already have an AWS account, skip to the next task. If you don't have an AWS account, perform the steps in the following procedure to create one.
To create an AWS account
1. Open https://portal.aws.amazon.com/billing/signup.
Create an IAM user
2. Follow the online instructions.
Part of the sign-up procedure involves receiving a phone call and entering a verification code on the phone keypad.
Note your AWS account ID because you'll need it for the next task.
Create an IAM user
Services in AWS, such as Amazon Rekognition, require that you provide credentials when you access them. This is so that the service can determine whether you have permissions to access the resources owned by that service. The console requires your password. You can create access keys for your AWS account to access the AWS CLI or API. However, we don't recommend that you access AWS by using the credentials for your AWS account root user. Instead, we recommend that you:
• Use AWS Identity and Access Management (IAM) to create an IAM user.
• Add the user to an IAM group with administrative permissions.
You can then access AWS by using a special URL and that IAM user's credentials.
If you signed up for AWS, but you haven't created an IAM user for yourself, you can create one by using the IAM console. Follow the procedure to create an IAM user in your account.
To create an IAM user and sign in to the console
1. Create an IAM user with administrator permissions in your AWS account. For instructions, see Creating Your First IAM User and Administrators Group in the IAM User Guide.
2. As the IAM user, sign in to the AWS Management Console by using a special URL. For more information, see How Users Sign In to Your Account in the IAM User Guide.
Note
An IAM user with administrator permissions has unrestricted access to the AWS services in your account. For information about restricting access to Amazon Rekognition operations, see Amazon Rekognition identity-based policies (p. 469). The code examples in this guide assume that you have a user with the AmazonRekognitionFullAccess permissions.
AmazonS3ReadOnlyAccess is required for examples that access images or videos that are stored in an Amazon S3 bucket. The Amazon Rekognition Video stored video code examples also require AmazonSQSFullAccess permissions. Depending on your security requirements, you might want to use an IAM group that's limited to these permissions. For more information, see Creating IAM Groups.
For more information about IAM, see the following:
• AWS Identity and Access Management (IAM)
• Getting started
• IAM User Guide
Next step
Step 2: Set up the AWS CLI and AWS SDKs (p. 13)
Step 2: Set up the AWS CLI and AWS SDKs
Step 2: Set up the AWS CLI and AWS SDKs
The following steps show you how to install the AWS Command Line Interface (AWS CLI) and AWS SDKs that the examples in this documentation use. There are a number of different ways to authenticate AWS SDK calls. The examples in this guide assume that you're using a default credentials profile for calling AWS CLI commands and AWS SDK API operations.
For a list of available AWS Regions, see Regions and Endpoints in the Amazon Web Services General Reference.
Follow the steps to download and configure the AWS SDKs.
To set up the AWS CLI and the AWS SDKs
1. Download and install the AWS CLI and the AWS SDKs that you want to use. This guide provides examples for the AWS CLI, Java, Python, Ruby, Node.js, PHP, .NET, and JavaScript. For information about installing AWS SDKs, see Tools for Amazon Web Services.
2. Create an access key for the user you created in Create an IAM user (p. 12).
a. Sign in to the AWS Management Console and open the IAM console at https://
console.aws.amazon.com/iam/.
b. In the navigation pane, choose Users.
c. Choose the name of the user you created in Create an IAM user (p. 12).
d. Choose the Security credentials tab.
e. Choose Create access key. Then choose Download .csv file to save the access key ID and secret access key to a CSV file on your computer. Store the file in a secure location. You will not have access to the secret access key again after this dialog box closes. After you have downloaded the CSV file, choose Close.
3. If you have installed the AWS CLI, you can configure the credentials and region for most AWS SDKs by entering aws configure at the command prompt. Otherwise, use the following instructions.
4. On your computer, navigate to your home directory, and create an .aws directory. On Unix-based systems, such as Linux or macOS, this is in the following location:
~/.aws
On Windows, this is in the following location:
%HOMEPATH%\.aws
5. In the .aws directory, create a new file named credentials.
6. Open the credentials CSV file that you created in step 2 and copy its contents into the credentials file using the following format:
[default]
aws_access_key_id = your_access_key_id
aws_secret_access_key = your_secret_access_key
Substitute your access key ID and secret access key for your_access_key_id and your_secret_access_key.
7. Save the Credentials file and delete the CSV file.
8. In the .aws directory, create a new file named config.
9. Open the config file and enter your region in the following format.
Next step
[default]
region = your_aws_region
Substitute your desired AWS Region (for example, us-west-2) for your_aws_region.
Note
If you don't select a region, then us-east-1 will be used by default.10. Save the config file.
Next step
Step 3: Getting started using the AWS CLI and AWS SDK API (p. 14)
Using Rekognition with an AWS SDK
AWS software development kits (SDKs) are available for many popular programming languages. Each SDK provides an API, code examples, and documentation that make it easier for developers to build applications in their preferred language.
SDK documentation Code examples
AWS SDK for C++ AWS SDK for C++ code examples
AWS SDK for Go AWS SDK for Go code examples
AWS SDK for Java AWS SDK for Java code examples
AWS SDK for JavaScript AWS SDK for JavaScript code examples
AWS SDK for .NET AWS SDK for .NET code examples
AWS SDK for PHP AWS SDK for PHP code examples
AWS SDK for Python (Boto3) AWS SDK for Python (Boto3) code examples
AWS SDK for Ruby AWS SDK for Ruby code examples
For examples specific to Rekognition, see Code examples for Amazon Rekognition (p. 374).
Example availability
Can't find what you need? Request a code example by using the Provide feedback link at the bottom of this page.
Step 3: Getting started using the AWS CLI and AWS SDK API
After you've set up the AWS CLI and AWS SDKs that you want to use, you can build applications that use Amazon Rekognition. The following topics show you how to get started with Amazon Rekognition Image and Amazon Rekognition Video.
• Working with images (p. 26)
Formatting the AWS CLI examples
• Working with stored videos (p. 60)
• Working with streaming videos (p. 90)
Formatting the AWS CLI examples
The AWS CLI examples in this guide are formatted for the Linux operating system. To use the samples with Microsoft Windows, you 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 that's 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.
Next step
Step 4: Getting started using the Amazon Rekognition console (p. 15)
Step 4: Getting started using the Amazon Rekognition console
This section shows you how to use a subset of Amazon Rekognition's capabilities such as object and scene detection, facial analysis, and face comparison in a set of images. For more information, see How Amazon Rekognition works (p. 4). You can also use the Amazon Rekognition API or AWS CLI to detect objects and scenes, detect faces, and compare and search faces. For more information, see Step 3:
Getting started using the AWS CLI and AWS SDK API (p. 14).
This section also shows you how to see aggregated Amazon CloudWatch metrics for Rekognition by using the Rekognition console.
Topics
• Exercise 1: Detect objects and scenes (Console) (p. 16)
• Exercise 2: Analyze faces in an image (console) (p. 20)
• Exercise 3: Compare faces in images (console) (p. 23)
• Exercise 4: See aggregated metrics (console) (p. 25)
Exercise 1: Detect objects and scenes (console)
Exercise 1: Detect objects and scenes (Console)
This section shows how, at a very high level, Amazon Rekognition's objects and scenes detection capability works. When you specify an image as input, the service detects the objects and scenes in the image and returns them along with a percent confidence score for each object and scene.
For example, Amazon Rekognition detects the following objects and scenes in the sample image:
skateboard, sport, person, auto, car and vehicle.
Amazon Rekognition also returns a confidence score for each object detected in the sample image, as shown in the following sample response.
Exercise 1: Detect objects and scenes (console)
To see all the confidence scores shown in the response, choose Show more in the Labels | Confidence pane.
You can also look at the request to the API and the response from the API as a reference.
Request
{
"contentString":{
"Attributes":[
"ALL"
], "Image":{
"S3Object":{
"Bucket":"console-sample-images", "Name":"skateboard.jpg"
} } }}
Response
{ "Labels":[
{
"Confidence":99.25359344482422, "Name":"Skateboard"
}, {
"Confidence":99.25359344482422, "Name":"Sport"
},
Exercise 1: Detect objects and scenes (console)
{
"Confidence":99.24723052978516, "Name":"People"
}, {
"Confidence":99.24723052978516, "Name":"Person"
}, {
"Confidence":99.23908233642578, "Name":"Human"
}, {
"Confidence":97.42484283447266, "Name":"Parking"
}, {
"Confidence":97.42484283447266, "Name":"Parking Lot"
}, {
"Confidence":91.53300476074219, "Name":"Automobile"
}, {
"Confidence":91.53300476074219, "Name":"Car"
}, {
"Confidence":91.53300476074219, "Name":"Vehicle"
}, {
"Confidence":76.85114288330078, "Name":"Intersection"
}, {
"Confidence":76.85114288330078, "Name":"Road"
}, {
"Confidence":76.21503448486328, "Name":"Boardwalk"
}, {
"Confidence":76.21503448486328, "Name":"Path"
}, {
"Confidence":76.21503448486328, "Name":"Pavement"
}, {
"Confidence":76.21503448486328, "Name":"Sidewalk"
}, {
"Confidence":76.21503448486328, "Name":"Walkway"
}, {
"Confidence":66.71541595458984, "Name":"Building"
}, {
"Confidence":62.04711151123047,
Exercise 1: Detect objects and scenes (console)
"Name":"Coupe"
}, {
"Confidence":62.04711151123047, "Name":"Sports Car"
}, {
"Confidence":61.98909378051758, "Name":"City"
}, {
"Confidence":61.98909378051758, "Name":"Downtown"
}, {
"Confidence":61.98909378051758, "Name":"Urban"
}, {
"Confidence":60.978023529052734, "Name":"Neighborhood"
}, {
"Confidence":60.978023529052734, "Name":"Town"
}, {
"Confidence":59.22066116333008, "Name":"Sedan"
}, {
"Confidence":56.48063278198242, "Name":"Street"
}, {
"Confidence":54.235477447509766, "Name":"Housing"
}, {
"Confidence":53.85226058959961, "Name":"Metropolis"
}, {
"Confidence":52.001792907714844, "Name":"Office Building"
}, {
"Confidence":51.325313568115234, "Name":"Suv"
}, {
"Confidence":51.26075744628906, "Name":"Apartment Building"
}, {
"Confidence":51.26075744628906, "Name":"High Rise"
}, {
"Confidence":50.68067932128906, "Name":"Pedestrian"
}, {
"Confidence":50.59548568725586, "Name":"Freeway"
},
Exercise 2: Analyze faces (console)
{
"Confidence":50.568580627441406, "Name":"Bumper"
} ]}
For more information, see How Amazon Rekognition works (p. 4).
Detect objects and scenes in an image you provide
You can upload an image that you own or provide the URL to an image as input in the Amazon Rekognition console. Amazon Rekognition returns the object and scenes, confidence scores for each object, and scene it detects in the image you provide.
Note
The image must be less than 5MB in size and must be of JPEG or PNG format.
To detect objects and scenes in an image you provide
1. Open the Amazon Rekognition console at https://console.aws.amazon.com/rekognition/.
2. Choose Label detection.
3. Do one of the following:
• Upload an image – Choose Upload, go to the location where you stored your image, and then select the image.
• Use a URL – Type the URL in the text box, and then choose Go.
4. View the confidence score of each label detected in the Labels | Confidence pane.
For more image analysis options, see the section called “Working with images” (p. 26).
Detect objects and people in a video you provide
You can upload a video that you provide as input in the Amazon Rekognition console. Amazon Rekognition returns the people, objects, and labels detected in the video.
Note
The demo video must not be more than a minute long or larger than 30 MB. It must be in MP4 file format and encoded using the H.264 codec.To detect objects and people in a video you provide
1. Open the Amazon Rekognition console at https://console.aws.amazon.com/rekognition/.
2. Choose Video analysis.
3. Under Choose a sample or upload your own, select Your own video.
4. Drag and drop your video or select your video from the location where you've stored it.
For more video analysis options, see the section called “Working with stored videos” (p. 60) or the section called “Working with streaming videos” (p. 90).
Exercise 2: Analyze faces in an image (console)
This section shows you how to use the Amazon Rekognition console to detect faces and analyze facial attributes in an image. When you provide an image that contains a face as input, the service detects the
Exercise 2: Analyze faces (console)
face in the image, analyzes the facial attributes of the face, and then returns a percent confidence score for the face and the facial attributes detected in the image. For more information, see How Amazon Rekognition works (p. 4).
For example, if you choose the following sample image as input, Amazon Rekognition detects it as a face and returns confidence scores for the face and the facial attributes detected.
The following shows the sample response.
Exercise 2: Analyze faces (console)
If there are multiple faces in the input image, Rekognition detects up to 100 faces in the image.
Each face detected is marked with a square. When you click the area marked with a square on a face, Rekognition displays the confidence score of that face and its attributes detected in the Faces | Confidence pane.
Analyze faces in an image you provide
You can upload your own image or provide the URL to the image in the Amazon Rekognition console.
Note
The image must be less than 5MB in size and must be of JPEG or PNG format.
To analyze a face in an image you provide
1. Open the Amazon Rekognition console at https://console.aws.amazon.com/rekognition/.
2. Choose Facial analysis.
Exercise 3: Compare faces (console)
3. Do one of the following:
• Upload an image – Choose Upload, go to the location where you stored your image, and then select the image.
• Use a URL – Type the URL in the text box, and then choose Go.
4. View the confidence score of one the faces detected and its facial attributes in the Faces | Confidence pane.
5. If there are multiple faces in the image, choose one of the other faces to see its attributes and scores.
Exercise 3: Compare faces in images (console)
This section shows you how to use the Amazon Rekognition console to compare faces within a set of images with multiple faces in them. When you specify a Reference face (source) and a Comparison faces (target) image, Rekognition compares the largest face in the source image (that is, the reference face) with up to 100 faces detected in the target image (that is, the comparison faces), and then finds how closely the face in the source matches the faces in the target image. The similarity score for each comparison is displayed in the Results pane.
If the target image contains multiple faces, Rekognition matches the face in the source image with up to 100 faces detected in target image, and then assigns a similarity score to each match.
If the source image contains multiple faces, the service detects the largest face in the source image and uses it to compare with each face detected in the target image.
For more information, see Comparing faces in images (p. 154).
For example, with the sample image shown on the left as a source image and the sample image on the right as a target image, Rekognition detects the face in the source image, compares it with each face detected in the target image, and displays a similarity score for each pair.
The following shows the faces detected in the target image and the similarity score for each face.
Exercise 3: Compare faces (console)
Compare faces in an image you provide
You can upload your own source and target images for Rekognition to compare the faces in the images or you can specify a URL for the location of the images.
Note
The image must be less than 5MB in size and must be of JPEG or PNG format.To compare faces in your images
1. Open the Amazon Rekognition console at https://console.aws.amazon.com/rekognition/.
2. Choose Face comparison.
3. For your source image, do one of the following:
• Upload an image – Choose Upload on the left, go to the location where you stored your source image, and then select the image.
• Use a URL – Type the URL of your source image in the text box, and then choose Go.
4. For your target image, do one of the following:
• Upload an image – Choose Upload on the right, go to the location where you stored your source image, and then select the image.
Exercise 4: See aggregated metrics (console)
• Use a URL – Type the URL of your source image in the text box, and then choose Go.
5. Rekognition matches the largest face in your source image with up to 100 faces in the target image and then displays the similarity score for each pair in the Results pane.
Exercise 4: See aggregated metrics (console)
The Amazon Rekognition metrics pane shows activity graphs for an aggregate of individual Rekognition metrics over a specified period of time. For example, the SuccessfulRequestCount aggregated metric shows the total number of successful requests to all Rekognition API operations over the last seven days.
The following table lists the graphs displayed in the Rekognition metrics pane and the corresponding Rekognition metric. For more information, see CloudWatch metrics for Rekognition (p. 485).
Graph Aggregated Metric
Successful calls SuccessfulRequestCount Client errors UserErrorCount
Server errors ServerErrorCount
Throttled ThrottledCount
Detected labels DetectedLabelCount Detected faces DetectedFaceCount
Each graph shows aggregated metric data collected over a specified period of time. A total count of aggregated metric data for the time period is also displayed. To see metrics for individual API calls, choose the link beneath each graph.
To allow users access to the Rekognition metrics pane, ensure that the user has appropriate CloudWatch and Rekognition permissions. For example, a user with AmazonRekognitionReadOnlyAccess and CloudWatchReadOnlyAccess managed policy permissions can see the metrics pane. If a user does not have the required permissions, when the user opens the metrics pane, no graphs appear. For more information, see Identity and access management for Amazon Rekognition (p. 465).
For more information about monitoring Rekognition with CloudWatch see Monitoring Rekognition (p. 483).
To see aggregated metrics (console)
1. Open the Amazon Rekognition console at https://console.aws.amazon.com/rekognition/.
2. In the navigation pane, choose Metrics.
3. In the dropdown, select the period of time you want metrics for.
4. To update the graphs, choose the Refresh button.
5. To see detailed CloudWatch metrics for a specific aggregated metric, choose See details on CloudWatch beneath the metric graph.
Working with images
Working with images and videos
You can use Amazon Rekognition API operations with images, stored videos, and streaming videos.
This section provides general information about writing code that accesses Amazon Rekognition. Other sections in this guide provide information about specific types of image and video analysis, such as face detection.
Topics
• Working with images (p. 26)
• Working with stored videos (p. 60)
• Working with streaming videos (p. 90)
• Error handling (p. 115)
• Using Amazon Rekognition as a FedRAMP authorized service (p. 120)
• Using Amazon Rekognition as a FedRAMP authorized service (p. 120)