Rekognition via SDK Best Practices

Q: What is the single most common Rekognition cost mistake?

Leaving a Custom Labels project version RUNNING when it isn't actively serving traffic. Inference-unit-hours bill continuously regardless of request volume, so an idle version left on overnight or over a weekend adds up fast.

Q: How should I handle video jobs at scale?

Use NotificationChannel so Rekognition pushes completion to SNS instead of polling, and always page through Get* results with NextToken rather than assuming one call returns everything.

This is the checklist to run before and after taking a Rekognition workload to production from the SDK.

Each item is a rule stated positively, with a one-line rationale. Work top to bottom - the groups run from tuning the model's output, through responsible use, request patterns, Custom Labels cost, and finally reliability and security. Most rules apply whether you call Rekognition from boto3 or the AWS SDK v3.

How to Use This List

Treat each box as an audit question against your own project.
The groups run from output tuning and responsible use outward to cost, reliability, and security.
Revisit the list whenever you add a new use case, a new Custom Labels project, or move from images to video.
Groups D and beyond apply mainly to teams running Custom Labels or high-volume video pipelines.

A - Confidence & Threshold Tuning

Tune MinConfidence against your own images. The service defaults are general-purpose starting points, not validated for your specific content.
Tune SimilarityThreshold deliberately for CompareFaces. The right value depends on the cost of a false positive versus a false negative in your specific flow.
Re-test thresholds when your image domain changes. A threshold tuned on product photos will not necessarily hold for user-uploaded selfies.
Treat an empty result as "below threshold," not "confirmed absent." No label crossing MinConfidence is not the same as a certified negative.

Tune per-operation rather than reusing one number everywhere.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
 
# Higher bar for a high-stakes verification flow; lower bar for casual tagging.
verify = rekognition.compare_faces(
    SourceImage={"S3Object": {"Bucket": "my-bucket", "Name": "reference.jpg"}},
    TargetImage={"S3Object": {"Bucket": "my-bucket", "Name": "submitted.jpg"}},
    SimilarityThreshold=90,
)
tag = rekognition.detect_labels(
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "catalog/item.jpg"}},
    MinConfidence=70,
)

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, CompareFacesCommand, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
 
// Higher bar for a high-stakes verification flow; lower bar for casual tagging.
const verify = await rekognition.send(new CompareFacesCommand({
  SourceImage: { S3Object: { Bucket: "my-bucket", Name: "reference.jpg" } },
  TargetImage: { S3Object: { Bucket: "my-bucket", Name: "submitted.jpg" } },
  SimilarityThreshold: 90,
}));
const tag = await rekognition.send(new DetectLabelsCommand({
  Image: { S3Object: { Bucket: "my-bucket", Name: "catalog/item.jpg" } },
  MinConfidence: 70,
}));

B - Responsible Use & Human Review

Never auto-decide on face output alone for consequential outcomes. Access control, identity verification, and moderation escalation deserve a human in the loop.
Route borderline confidence scores to review, not a hard cutoff. A single threshold at the boundary is where accuracy variance matters most.
Do not treat estimated attributes as verified facts about a person. Age range, gender, and emotion are population-level statistical estimates, not confirmed identity data.
Document your threshold choices and why. A recorded rationale makes it possible to audit and revisit decisions later, especially after an incident.

C - Image & Video Request Patterns

Use S3Object references for large images and all video. Image.Bytes caps at 5 MB; video operations only accept S3Object, never raw bytes.
Prefer SNS notifications over polling for video jobs. NotificationChannel avoids wasted Get* calls and reduces latency versus a fixed poll interval.
Page through every Get result with NextToken.* A long video's labels, faces, or moderation entries can span many response pages.
Check JobStatus for FAILED, not just SUCCEEDED. A loop that only exits on success can hang forever on a failed job.
Cache results keyed by object version or content hash. Re-running detection on an unchanged image bills again for no new information.

D - Custom Labels Cost Control

Stop project versions when not actively serving requests. Inference-unit-hours bill continuously while RUNNING, independent of call volume.
Automate start/stop around actual demand. Tie StartProjectVersion/StopProjectVersion to a batch job's lifecycle or a scaling policy rather than leaving a version on by default.
Keep training and testing data strictly separate. Overlapping sets inflate evaluation metrics and hide real-world accuracy problems.
Create a new version to retrain instead of expecting in-place updates. Versions are immutable once trained - compare metrics before switching production traffic.

Automate the start/stop discipline instead of relying on manual cleanup.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
version_arn = "arn:aws:rekognition:us-east-1:123456789012:project/parts-inspector/version/v1/1700000000000"
 
# Start before a batch job, stop immediately after - never leave it running idle.
rekognition.start_project_version(ProjectVersionArn=version_arn, MinInferenceUnits=1)
try:
    pass  # ... run DetectCustomLabels calls here ...
finally:
    rekognition.stop_project_version(ProjectVersionArn=version_arn)

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, StartProjectVersionCommand, StopProjectVersionCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
const versionArn = "arn:aws:rekognition:us-east-1:123456789012:project/parts-inspector/version/v1/1700000000000";
 
// Start before a batch job, stop immediately after - never leave it running idle.
await rekognition.send(new StartProjectVersionCommand({ ProjectVersionArn: versionArn, MinInferenceUnits: 1 }));
try {
  // ... run DetectCustomLabels calls here ...
} finally {
  await rekognition.send(new StopProjectVersionCommand({ ProjectVersionArn: versionArn }));
}

E - Reliability & Error Handling

Reuse one client across calls. A module-scoped client shares connection pooling and resolved credentials, cutting latency and overhead.
Handle throttling with retries, not a hard failure. Rekognition returns throttling errors under load; configure retries rather than surfacing them straight to users.
Validate face count before CompareFaces. A multi-face SourceImage fails the call - check with DetectFaces first if the source isn't guaranteed to be a single face.
Log the request id on failures. Capture the request identifier from the response metadata so AWS support can trace a specific call.

F - Security & Operations

Grant least-privilege IAM for Rekognition and any referenced S3 buckets. Scope to specific operations and bucket ARNs rather than broad wildcard access.
Verify the NotificationChannel role's trust policy. The IAM role Rekognition assumes to publish to SNS must explicitly trust the Rekognition service principal.
Store and process images/video with the same data-handling controls as any other user content. Rekognition inputs often include personal or sensitive imagery - apply your existing encryption and access controls.
Monitor Custom Labels running versions with CloudWatch or a scheduled check. A forgotten RUNNING version is a silent, ongoing cost until someone notices.

FAQs

What is the single most common Rekognition cost mistake?

Leaving a Custom Labels project version RUNNING when it isn't actively serving traffic. Inference-unit-hours bill continuously regardless of request volume, so an idle version left on overnight or over a weekend adds up fast.

Should I use the default MinConfidence and SimilarityThreshold values?

Only as a starting point. Test both against a labeled sample of your own images and tune per use case - a high-stakes verification flow and a casual tagging feature warrant very different thresholds.

Is it safe to auto-approve or auto-reject based on a confidence score alone?

For anything consequential to a person, no. Use confidence bands with a human review step for borderline cases, and never treat estimated face attributes as verified facts.

How should I handle video jobs at scale?

Use NotificationChannel so Rekognition pushes completion to SNS instead of polling, and always page through Get* results with NextToken rather than assuming one call returns everything.

Do these rules apply equally to boto3 and the SDK v3?

Yes. Confidence tuning, responsible use, Custom Labels start/stop discipline, and reliability patterns are the same regardless of which SDK you call Rekognition from - only the syntax differs.

Should I make a new client per request?

No. Create one client and reuse it across calls so connection pooling and resolved credentials are shared, which lowers latency, especially in long-running services or warm Lambda invocations.

What's the fastest way to catch a forgotten running Custom Labels version?

Add a scheduled check (a cron job or CloudWatch alarm) that lists project versions and alerts if any are RUNNING outside expected batch windows, since there is no automatic idle-shutoff.

Rekognition's Pretrained Vision Model Surface - the pretrained/Custom Labels split behind groups A and D.
Face Detection, Comparison & Analysis - the responsible-use guidance behind group B.
Video Analysis with Asynchronous Operations - the request patterns in group C.
Custom Labels for Domain-Specific Detection - the cost model behind group D.

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 via SDK Best Practices

This is the checklist to run before and after taking a Rekognition workload to production from the SDK.

How to Use This List

Treat each box as an audit question against your own project.
The groups run from output tuning and responsible use outward to cost, reliability, and security.
Revisit the list whenever you add a new use case, a new Custom Labels project, or move from images to video.
Groups D and beyond apply mainly to teams running Custom Labels or high-volume video pipelines.

A - Confidence & Threshold Tuning

Tune MinConfidence against your own images. The service defaults are general-purpose starting points, not validated for your specific content.
Tune SimilarityThreshold deliberately for CompareFaces. The right value depends on the cost of a false positive versus a false negative in your specific flow.
Re-test thresholds when your image domain changes. A threshold tuned on product photos will not necessarily hold for user-uploaded selfies.
Treat an empty result as "below threshold," not "confirmed absent." No label crossing MinConfidence is not the same as a certified negative.

Tune per-operation rather than reusing one number everywhere.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
 
# Higher bar for a high-stakes verification flow; lower bar for casual tagging.
verify = rekognition.compare_faces(
    SourceImage={"S3Object": {"Bucket": "my-bucket", "Name": "reference.jpg"}},
    TargetImage={"S3Object": {"Bucket": "my-bucket", "Name": "submitted.jpg"}},
    SimilarityThreshold=90,
)
tag = rekognition.detect_labels(
    Image={"S3Object": {"Bucket": "my-bucket", "Name": "catalog/item.jpg"}},
    MinConfidence=70,
)

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, CompareFacesCommand, DetectLabelsCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
 
// Higher bar for a high-stakes verification flow; lower bar for casual tagging.
const verify = await rekognition.send(new CompareFacesCommand({
  SourceImage: { S3Object: { Bucket: "my-bucket", Name: "reference.jpg" } },
  TargetImage: { S3Object: { Bucket: "my-bucket", Name: "submitted.jpg" } },
  SimilarityThreshold: 90,
}));
const tag = await rekognition.send(new DetectLabelsCommand({
  Image: { S3Object: { Bucket: "my-bucket", Name: "catalog/item.jpg" } },
  MinConfidence: 70,
}));

B - Responsible Use & Human Review

Never auto-decide on face output alone for consequential outcomes. Access control, identity verification, and moderation escalation deserve a human in the loop.
Route borderline confidence scores to review, not a hard cutoff. A single threshold at the boundary is where accuracy variance matters most.
Do not treat estimated attributes as verified facts about a person. Age range, gender, and emotion are population-level statistical estimates, not confirmed identity data.
Document your threshold choices and why. A recorded rationale makes it possible to audit and revisit decisions later, especially after an incident.

C - Image & Video Request Patterns

Use S3Object references for large images and all video. Image.Bytes caps at 5 MB; video operations only accept S3Object, never raw bytes.
Prefer SNS notifications over polling for video jobs. NotificationChannel avoids wasted Get* calls and reduces latency versus a fixed poll interval.
Page through every Get result with NextToken.* A long video's labels, faces, or moderation entries can span many response pages.
Check JobStatus for FAILED, not just SUCCEEDED. A loop that only exits on success can hang forever on a failed job.
Cache results keyed by object version or content hash. Re-running detection on an unchanged image bills again for no new information.

D - Custom Labels Cost Control

Stop project versions when not actively serving requests. Inference-unit-hours bill continuously while RUNNING, independent of call volume.
Automate start/stop around actual demand. Tie StartProjectVersion/StopProjectVersion to a batch job's lifecycle or a scaling policy rather than leaving a version on by default.
Keep training and testing data strictly separate. Overlapping sets inflate evaluation metrics and hide real-world accuracy problems.
Create a new version to retrain instead of expecting in-place updates. Versions are immutable once trained - compare metrics before switching production traffic.

Automate the start/stop discipline instead of relying on manual cleanup.

# --- Python (boto3) ---
import boto3
 
rekognition = boto3.client("rekognition")
version_arn = "arn:aws:rekognition:us-east-1:123456789012:project/parts-inspector/version/v1/1700000000000"
 
# Start before a batch job, stop immediately after - never leave it running idle.
rekognition.start_project_version(ProjectVersionArn=version_arn, MinInferenceUnits=1)
try:
    pass  # ... run DetectCustomLabels calls here ...
finally:
    rekognition.stop_project_version(ProjectVersionArn=version_arn)

// --- TypeScript (AWS SDK v3) ---
import { RekognitionClient, StartProjectVersionCommand, StopProjectVersionCommand } from "@aws-sdk/client-rekognition";
 
const rekognition = new RekognitionClient({});
const versionArn = "arn:aws:rekognition:us-east-1:123456789012:project/parts-inspector/version/v1/1700000000000";
 
// Start before a batch job, stop immediately after - never leave it running idle.
await rekognition.send(new StartProjectVersionCommand({ ProjectVersionArn: versionArn, MinInferenceUnits: 1 }));
try {
  // ... run DetectCustomLabels calls here ...
} finally {
  await rekognition.send(new StopProjectVersionCommand({ ProjectVersionArn: versionArn }));
}

E - Reliability & Error Handling

Reuse one client across calls. A module-scoped client shares connection pooling and resolved credentials, cutting latency and overhead.
Handle throttling with retries, not a hard failure. Rekognition returns throttling errors under load; configure retries rather than surfacing them straight to users.
Validate face count before CompareFaces. A multi-face SourceImage fails the call - check with DetectFaces first if the source isn't guaranteed to be a single face.
Log the request id on failures. Capture the request identifier from the response metadata so AWS support can trace a specific call.

F - Security & Operations

Grant least-privilege IAM for Rekognition and any referenced S3 buckets. Scope to specific operations and bucket ARNs rather than broad wildcard access.
Verify the NotificationChannel role's trust policy. The IAM role Rekognition assumes to publish to SNS must explicitly trust the Rekognition service principal.
Store and process images/video with the same data-handling controls as any other user content. Rekognition inputs often include personal or sensitive imagery - apply your existing encryption and access controls.
Monitor Custom Labels running versions with CloudWatch or a scheduled check. A forgotten RUNNING version is a silent, ongoing cost until someone notices.

FAQs

What is the single most common Rekognition cost mistake?

Should I use the default MinConfidence and SimilarityThreshold values?

Only as a starting point. Test both against a labeled sample of your own images and tune per use case - a high-stakes verification flow and a casual tagging feature warrant very different thresholds.

Is it safe to auto-approve or auto-reject based on a confidence score alone?

For anything consequential to a person, no. Use confidence bands with a human review step for borderline cases, and never treat estimated face attributes as verified facts.

How should I handle video jobs at scale?

Use NotificationChannel so Rekognition pushes completion to SNS instead of polling, and always page through Get* results with NextToken rather than assuming one call returns everything.

Do these rules apply equally to boto3 and the SDK v3?

Yes. Confidence tuning, responsible use, Custom Labels start/stop discipline, and reliability patterns are the same regardless of which SDK you call Rekognition from - only the syntax differs.

Should I make a new client per request?

No. Create one client and reuse it across calls so connection pooling and resolved credentials are shared, which lowers latency, especially in long-running services or warm Lambda invocations.

What's the fastest way to catch a forgotten running Custom Labels version?

Add a scheduled check (a cron job or CloudWatch alarm) that lists project versions and alerts if any are RUNNING outside expected batch windows, since there is no automatic idle-shutoff.

Rekognition's Pretrained Vision Model Surface - the pretrained/Custom Labels split behind groups A and D.
Face Detection, Comparison & Analysis - the responsible-use guidance behind group B.
Video Analysis with Asynchronous Operations - the request patterns in group C.
Custom Labels for Domain-Specific Detection - the cost model behind group D.

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 via SDK Best Practices

Buscar en la documentación

Rekognition via SDK Best Practices