Rekognition Basics

Six examples to get you started with Amazon Rekognition - four basic and two intermediate.

Each example shows the same operation in both Python (boto3) and TypeScript (AWS SDK for JavaScript v3). Every call here is a synchronous image operation; video analysis works differently and is covered later in this section.

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-rekognition (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role - the SDK resolves them automatically.
An image to test with, either a local JPEG/PNG file or one already uploaded to an S3 bucket you can read.

Basic Examples

1. Detect Labels from a Local Image

DetectLabels finds objects, scenes, and concepts in an image and returns them with confidence scores.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition", region_name="us-east-1")
 
with open("photo.jpg", "rb") as f:
    image_bytes = f.read()
 
response = rekognition.detect_labels(
    Image={"Bytes": image_bytes},
    MaxLabels=10,
)
for label in response["Labels"]:
    print(label["Name"], label["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({ region: "us-east-1" });
const imageBytes = readFileSync("photo.jpg");
 
const response = await rekognition.send(new DetectLabelsCommand({
  Image: { Bytes: imageBytes },
  MaxLabels: 10,
}));
for (const label of response.Labels ?? []) console.log(label.Name, label.Confidence);

Image.Bytes takes the raw file bytes directly, up to 5 MB for this path.
Labels comes back sorted by confidence, each with a Name and a Confidence percentage.
MaxLabels caps how many results return; omit it to get every label above the confidence floor.
No training or setup is required - this is a pretrained model you call directly.

Related: Rekognition's Pretrained Vision Model Surface - what this model does and does not cover.

2. Detect Labels from an Object Already in S3

For images larger than 5 MB, or already stored in your pipeline, reference an S3 object instead of sending bytes.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
response = rekognition.detect_labels(
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "uploads/photo.jpg"}},
    MinConfidence=75,
)
for label in response["Labels"]:
    print(label["Name"], label["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectLabelsCommand({
  Image: { S3Object: { Bucket: "my-bucket", Name: "uploads/photo.jpg" } },
  MinConfidence: 75,
}));
for (const label of response.Labels ?? []) console.log(label.Name, label.Confidence);

S3Object avoids reading the file into your process at all; Rekognition fetches it directly.
MinConfidence filters out low-certainty labels server-side instead of you filtering the response.
Rekognition needs s3:GetObject permission on the bucket to read the referenced key.
This is the pattern to use for images already produced by an upload pipeline.

3. Detect Faces with Attributes

DetectFaces locates faces in an image and, with Attributes: ["ALL"], returns age range, emotions, and landmarks for each.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
with open("portrait.jpg", "rb") as f:
    response = rekognition.detect_faces(
        Image={"Bytes": f.read()},
        Attributes=["ALL"],
    )
 
for face in response["FaceDetails"]:
    age = face["AgeRange"]
    top_emotion = max(face["Emotions"], key=lambda e: e["Confidence"])
    print(f"age {age['Low']}-{age['High']}, mood: {top_emotion['Type']}")

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectFacesCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectFacesCommand({
  Image: { Bytes: readFileSync("portrait.jpg") },
  Attributes: ["ALL"],
}));
 
for (const face of response.FaceDetails ?? []) {
  const age = face.AgeRange;
  const topEmotion = face.Emotions?.sort((a, b) => (b.Confidence ?? 0) - (a.Confidence ?? 0))[0];
  console.log(`age ${age?.Low}-${age?.High}, mood: ${topEmotion?.Type}`);
}

Without Attributes: ["ALL"], only bounding boxes and overall confidence are returned - attributes are opt-in.
AgeRange is an estimate range, not a single number; treat it as approximate.
Emotions is a list of possible emotions each with its own confidence, not a single label.
Face attribute predictions vary in accuracy - use them as one signal, not a definitive judgment about a person.

4. Detect Unsafe Content

DetectModerationLabels flags an image for categories of unsafe or inappropriate content, each with a confidence score.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
with open("upload.jpg", "rb") as f:
    response = rekognition.detect_moderation_labels(
        Image={"Bytes": f.read()},
        MinConfidence=60,
    )
 
for label in response["ModerationLabels"]:
    print(label["Name"], label["ParentName"], label["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectModerationLabelsCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectModerationLabelsCommand({
  Image: { Bytes: readFileSync("upload.jpg") },
  MinConfidence: 60,
}));
 
for (const label of response.ModerationLabels ?? []) {
  console.log(label.Name, label.ParentName, label.Confidence);
}

Moderation labels come in a two-level taxonomy - a specific Name under a broader ParentName category.
An empty ModerationLabels list means nothing crossed MinConfidence - not a guarantee the image is safe.
Use this on user-generated content before it is stored or shown to other users.
Pair automated flags with a human review queue for anything near your confidence threshold.

Related: Content Moderation for Images & Video - moderation in depth, including video.

Intermediate Examples

5. Compare Two Faces

CompareFaces measures how similar a face in a target image is to a face in a source image.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
with open("source.jpg", "rb") as source, open("target.jpg", "rb") as target:
    response = rekognition.compare_faces(
        SourceImage={"Bytes": source.read()},
        TargetImage={"Bytes": target.read()},
        SimilarityThreshold=80,
    )
 
for match in response["FaceMatches"]:
    print(match["Similarity"], match["Face"]["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, CompareFacesCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new CompareFacesCommand({
  SourceImage: { Bytes: readFileSync("source.jpg") },
  TargetImage: { Bytes: readFileSync("target.jpg") },
  SimilarityThreshold: 80,
}));
 
for (const match of response.FaceMatches ?? []) {
  console.log(match.Similarity, match.Face?.Confidence);
}

SimilarityThreshold filters matches server-side; faces below it land in UnmatchedFaces instead.
SourceImage must contain exactly one face; TargetImage can contain several, each checked against it.
Similarity is a score, not an identity guarantee - use a conservative threshold and human review for consequential decisions.
This is the building block behind face-based verification flows, covered next in this section.

Related: Face Detection, Comparison & Analysis - CompareFaces, thresholds, and responsible use.

6. Tune Results with MinConfidence and MaxLabels Together

Combine both parameters to control precision and volume in one call, useful once you know your data.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
response = rekognition.detect_labels(
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "catalog/item-42.jpg"}},
    MaxLabels=5,
    MinConfidence=90,
)
print([l["Name"] for l in response["Labels"]])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectLabelsCommand({
  Image: { S3Object: { Bucket: "my-bucket", Name: "catalog/item-42.jpg" } },
  MaxLabels: 5,
  MinConfidence: 90,
}));
console.log((response.Labels ?? []).map((l) => l.Name));

A high MinConfidence (90+) trades recall for precision - fewer labels, but each more certain.
MaxLabels and MinConfidence combine: Rekognition returns up to MaxLabels results that also clear the confidence bar.
Tune both against a sample of your own images rather than guessing at defaults.
The response also includes Instances (bounding boxes) and Parents (category hierarchy) per label for further filtering.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Prerequisites

Python: pip install boto3 (boto3 1.43.x, Python 3.10+). TypeScript: npm install @aws-sdk/client-rekognition (Node.js 18+).
Credentials configured via aws configure, environment variables, or an IAM role - the SDK resolves them automatically.
An image to test with, either a local JPEG/PNG file or one already uploaded to an S3 bucket you can read.

Basic Examples

1. Detect Labels from a Local Image

DetectLabels finds objects, scenes, and concepts in an image and returns them with confidence scores.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition", region_name="us-east-1")
 
with open("photo.jpg", "rb") as f:
    image_bytes = f.read()
 
response = rekognition.detect_labels(
    Image={"Bytes": image_bytes},
    MaxLabels=10,
)
for label in response["Labels"]:
    print(label["Name"], label["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({ region: "us-east-1" });
const imageBytes = readFileSync("photo.jpg");
 
const response = await rekognition.send(new DetectLabelsCommand({
  Image: { Bytes: imageBytes },
  MaxLabels: 10,
}));
for (const label of response.Labels ?? []) console.log(label.Name, label.Confidence);

Image.Bytes takes the raw file bytes directly, up to 5 MB for this path.
Labels comes back sorted by confidence, each with a Name and a Confidence percentage.
MaxLabels caps how many results return; omit it to get every label above the confidence floor.
No training or setup is required - this is a pretrained model you call directly.

Related: Rekognition's Pretrained Vision Model Surface - what this model does and does not cover.

2. Detect Labels from an Object Already in S3

For images larger than 5 MB, or already stored in your pipeline, reference an S3 object instead of sending bytes.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
response = rekognition.detect_labels(
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "uploads/photo.jpg"}},
    MinConfidence=75,
)
for label in response["Labels"]:
    print(label["Name"], label["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectLabelsCommand({
  Image: { S3Object: { Bucket: "my-bucket", Name: "uploads/photo.jpg" } },
  MinConfidence: 75,
}));
for (const label of response.Labels ?? []) console.log(label.Name, label.Confidence);

S3Object avoids reading the file into your process at all; Rekognition fetches it directly.
MinConfidence filters out low-certainty labels server-side instead of you filtering the response.
Rekognition needs s3:GetObject permission on the bucket to read the referenced key.
This is the pattern to use for images already produced by an upload pipeline.

3. Detect Faces with Attributes

DetectFaces locates faces in an image and, with Attributes: ["ALL"], returns age range, emotions, and landmarks for each.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
with open("portrait.jpg", "rb") as f:
    response = rekognition.detect_faces(
        Image={"Bytes": f.read()},
        Attributes=["ALL"],
    )
 
for face in response["FaceDetails"]:
    age = face["AgeRange"]
    top_emotion = max(face["Emotions"], key=lambda e: e["Confidence"])
    print(f"age {age['Low']}-{age['High']}, mood: {top_emotion['Type']}")

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectFacesCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectFacesCommand({
  Image: { Bytes: readFileSync("portrait.jpg") },
  Attributes: ["ALL"],
}));
 
for (const face of response.FaceDetails ?? []) {
  const age = face.AgeRange;
  const topEmotion = face.Emotions?.sort((a, b) => (b.Confidence ?? 0) - (a.Confidence ?? 0))[0];
  console.log(`age ${age?.Low}-${age?.High}, mood: ${topEmotion?.Type}`);
}

Without Attributes: ["ALL"], only bounding boxes and overall confidence are returned - attributes are opt-in.
AgeRange is an estimate range, not a single number; treat it as approximate.
Emotions is a list of possible emotions each with its own confidence, not a single label.
Face attribute predictions vary in accuracy - use them as one signal, not a definitive judgment about a person.

4. Detect Unsafe Content

DetectModerationLabels flags an image for categories of unsafe or inappropriate content, each with a confidence score.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
with open("upload.jpg", "rb") as f:
    response = rekognition.detect_moderation_labels(
        Image={"Bytes": f.read()},
        MinConfidence=60,
    )
 
for label in response["ModerationLabels"]:
    print(label["Name"], label["ParentName"], label["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectModerationLabelsCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectModerationLabelsCommand({
  Image: { Bytes: readFileSync("upload.jpg") },
  MinConfidence: 60,
}));
 
for (const label of response.ModerationLabels ?? []) {
  console.log(label.Name, label.ParentName, label.Confidence);
}

Moderation labels come in a two-level taxonomy - a specific Name under a broader ParentName category.
An empty ModerationLabels list means nothing crossed MinConfidence - not a guarantee the image is safe.
Use this on user-generated content before it is stored or shown to other users.
Pair automated flags with a human review queue for anything near your confidence threshold.

Related: Content Moderation for Images & Video - moderation in depth, including video.

Intermediate Examples

5. Compare Two Faces

CompareFaces measures how similar a face in a target image is to a face in a source image.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
with open("source.jpg", "rb") as source, open("target.jpg", "rb") as target:
    response = rekognition.compare_faces(
        SourceImage={"Bytes": source.read()},
        TargetImage={"Bytes": target.read()},
        SimilarityThreshold=80,
    )
 
for match in response["FaceMatches"]:
    print(match["Similarity"], match["Face"]["Confidence"])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, CompareFacesCommand } from "@aws-sdk/client-rekognition";
import { readFileSync } from "node:fs";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new CompareFacesCommand({
  SourceImage: { Bytes: readFileSync("source.jpg") },
  TargetImage: { Bytes: readFileSync("target.jpg") },
  SimilarityThreshold: 80,
}));
 
for (const match of response.FaceMatches ?? []) {
  console.log(match.Similarity, match.Face?.Confidence);
}

SimilarityThreshold filters matches server-side; faces below it land in UnmatchedFaces instead.
SourceImage must contain exactly one face; TargetImage can contain several, each checked against it.
Similarity is a score, not an identity guarantee - use a conservative threshold and human review for consequential decisions.
This is the building block behind face-based verification flows, covered next in this section.

Related: Face Detection, Comparison & Analysis - CompareFaces, thresholds, and responsible use.

6. Tune Results with MinConfidence and MaxLabels Together

Combine both parameters to control precision and volume in one call, useful once you know your data.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
response = rekognition.detect_labels(
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "catalog/item-42.jpg"}},
    MaxLabels=5,
    MinConfidence=90,
)
print([l["Name"] for l in response["Labels"]])

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
const response = await rekognition.send(new DetectLabelsCommand({
  Image: { S3Object: { Bucket: "my-bucket", Name: "catalog/item-42.jpg" } },
  MaxLabels: 5,
  MinConfidence: 90,
}));
console.log((response.Labels ?? []).map((l) => l.Name));

A high MinConfidence (90+) trades recall for precision - fewer labels, but each more certain.
MaxLabels and MinConfidence combine: Rekognition returns up to MaxLabels results that also clear the confidence bar.
Tune both against a sample of your own images rather than guessing at defaults.
The response also includes Instances (bounding boxes) and Parents (category hierarchy) per label for further filtering.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Rekognition Basics

Search Documentation

Rekognition Basics