AWS Rekognition ExecModule

Overview

AwsRekognitionModule brings Amazon Rekognition Image analysis into ValkyrAI workflows. It covers the five analysis types in n8n's AWS Rekognition node while adding strict source validation, immutable S3 versions, verified IntegrationAccount credentials, explicit biometric-processing confirmation, bounded normalized output, credential redaction, deterministic attempt accounting, and annotation-backed Workflow Studio discovery.

The connector implements five synchronous operations:

• detect_labels identifies objects, scenes, actions, and concepts.
• detect_moderation_labels identifies hierarchical unsafe-content categories.
• detect_text extracts LINE and WORD detections with geometry.
• detect_faces returns face locations and selected attributes after explicit confirmation.
• recognize_celebrities returns provider celebrity matches after explicit confirmation.

Amazon Rekognition analysis is probabilistic. Results are evidence for a reviewed workflow, not a sole basis for decisions affecting a person's rights, eligibility, identity, employment, finances, healthcare, safety, or access to services.

Usage

1. Create a dedicated AWS IAM principal with only the Rekognition actions and S3 object reads required by the workflow.
2. Store its access key ID and secret access key in an AWS IntegrationAccount, verify the account, and keep it in READY status.
3. Add AwsRekognitionModule to a workflow and bind the account through ExecModuleConfig.authConfig.integrationAccount.
4. Choose an exact AWS region and exactly one image source:
   • imageBase64 for bounded JPEG or PNG bytes, or
   • s3Bucket, s3Key, and optional s3Version for an S3 object.
5. Select an operation. Set confirmBiometricProcessing: true only after the workflow is authorized to run face or celebrity analysis.
6. Preserve the immutable image reference, operation, thresholds, modelVersion, and requestId for audit and human review.

Never place AWS credentials in image input, logs, examples, or output. Credential-like input fields are rejected before provider access.

Inputs

Name	Type	Required for	Default	Constraints
operation	string	Every execution	None	One of the five documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2; custom endpoints are not accepted.
imageBase64	string	Optional inline source	None	Strict base64 JPEG or PNG; decoded bytes must be 1 byte through 5 MiB. Mutually exclusive with S3 fields.
s3Bucket	string	S3 source	None	Exact DNS-compatible bucket name.
s3Key	string	S3 source	None	Non-empty exact object key, at most 1,024 UTF-8 bytes.
s3Version	string	Optional S3 source	None	Exact object version, at most 1,024 characters. Prefer it for repeatable workflows.
minConfidence	number	Label or moderation analysis	80	0-100. Lower values increase recall and false positives.
maxLabels	integer	detect_labels	100	1-1,000 highest-confidence general labels.
faceAttributes	array	detect_faces	["DEFAULT"]	Exactly one value: DEFAULT or ALL.
confirmBiometricProcessing	boolean	Face or celebrity analysis	false	Must be true for detect_faces and recognize_celebrities.

The module rejects operation-specific parameters on unrelated operations. For example, maxLabels is invalid for moderation or text detection, and faceAttributes is invalid outside detect_faces.

Outputs

Every execution returns stable status, operation, and attempts fields.

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation.
attempts	integer	Always	Provider calls. Every analysis is single-attempt.
resultType	string	Success	labels, moderationLabels, textDetections, faces, or celebrities.
items	array	Success	Bounded normalized findings for the selected operation.
count	integer	Success	Number of returned findings.
modelVersion	string	Provider reports one	Label, moderation, or text model version.
orientationCorrection	string	Provider reports one	Image rotation metadata returned for supported operations.
contentTypes	array	Moderation response reports values	Predicted content form such as illustrated or animated.
unrecognizedFaceCount	integer	Celebrity analysis	Number of detected faces without a celebrity match.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Normalized label items can include name, confidence, parents, aliases, categories, and bounded instances with confidence and bounding boxes. Text items include text, LINE/WORD type, provider IDs, confidence, and geometry. Face items include confidence, bounding box, age range, pose, quality, and returned emotions. Celebrity items include provider ID, name, match confidence, and bounded reference URLs.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

Field	Requirement
Provider	Amazon Web Services / Rekognition
status	Must be READY.
verified	Must be true.
apiKey SecureField	AWS access key ID.
password SecureField	AWS secret access key.

Grant only the actions selected by the workflow:

• rekognition:DetectLabels
• rekognition:DetectModerationLabels
• rekognition:DetectText
• rekognition:DetectFaces
• rekognition:RecognizeCelebrities
• s3:GetObject and, for version-pinned images, s3:GetObjectVersion on exact input object ARNs

Separate face and celebrity workflows from ordinary labeling or moderation accounts when policy requires stronger biometric controls. The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, VPC endpoint overrides, custom label projects, moderation adapters, human-loop configuration, face collections, face comparison/search, streaming video, stored video jobs, and liveness analysis are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Operation, region, source, thresholds, face details, and biometric confirmation belong in module parameters or mapped input.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-rekognition-production"
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"detect_moderation_labels\",\"region\":\"us-west-2\",\"minConfidence\":85}"
  }
}

The relationship value is illustrative. Persisted workflows bind the generated IntegrationAccount relationship, never plaintext credentials.

Operations

Operation	Provider behavior	Side effect and retry behavior
detect_labels	Detects bounded objects, scenes, actions, concepts, aliases, categories, and instances.	Non-storage but billable external processing; exactly one provider attempt.
detect_moderation_labels	Detects hierarchical moderation labels above minConfidence.	Non-storage but billable external processing; exactly one provider attempt.
detect_text	Detects LINE and WORD text with geometry.	Non-storage but billable external processing; exactly one provider attempt.
detect_faces	Detects faces and DEFAULT or ALL attributes.	Biometric processing; explicit confirmation and exactly one provider attempt.
recognize_celebrities	Matches detected faces against Amazon's celebrity catalog.	Biometric processing; explicit confirmation and exactly one provider attempt.

The module does not mutate the source image or persist face collections. AWS may retain service telemetry under the account's AWS terms and configuration; review that policy before processing restricted images.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/ambiguous source, malformed region or S3 input, unsupported bytes, invalid threshold/bound, misplaced option, or missing biometric confirmation.	No	Correct the named input; no provider request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_ERROR	Account missing, unverified, not READY, or missing key material.	No	Repair and bind the AWS account.
AWS_REKOGNITION_HTTP_400	Invalid image, unsupported format, image too large, invalid S3 source, or provider limit.	Usually no	Validate the exact image, region, operation, and source.
AWS_REKOGNITION_HTTP_403	IAM denies Rekognition or S3 access.	No	Grant only the missing action on the intended object.
AWS_REKOGNITION_HTTP_429 / 500 / 503	Provider throttle or transient service pressure.	Reported as retryable, not automatically replayed	Reconcile the immutable image, request evidence, and billing before an orchestrated retry.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Reported as retryable, not automatically replayed	Treat the billable result as ambiguous and inspect AWS request logs before replay.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve the operation, source version, model version, and request evidence.

Provider exception text is never copied into output, preventing credential echoes and unbounded provider payloads.

Example

Moderate an immutable product image before publication:

{
  "operation": "detect_moderation_labels",
  "region": "us-west-2",
  "s3Bucket": "reviewed-product-assets",
  "s3Key": "catalog/2026/item-1042.jpg",
  "s3Version": "immutable-version-id",
  "minConfidence": 85
}

Expected result shape:

{
  "status": "success",
  "operation": "detect_moderation_labels",
  "attempts": 1,
  "resultType": "moderationLabels",
  "count": 1,
  "modelVersion": "provider-model-version",
  "requestId": "aws-request-reference",
  "items": [
    {
      "name": "Weapons",
      "parentName": "Violence",
      "taxonomyLevel": 2,
      "confidence": 94.2
    }
  ],
  "contentTypes": [
    {"name": "Illustrated", "confidence": 99.9}
  ]
}

The expected workflow routes any finding over its policy threshold into human review. An empty result does not prove an image is universally safe; it only means the selected model and threshold returned no matching label.

Notes

• Pagination: Rekognition Image operations return one synchronous response and do not expose pagination tokens. maxLabels bounds general-label output to 1-1,000 items; other provider result counts are bounded by the service operation.
• Rate limits: quotas vary by operation, account, and region. The AWS SDK's own retries are disabled so attempt accounting is deterministic. Throttling is marked retryable, but the module does not automatically replay billable analysis.
• API limits: inline input is restricted to JPEG or PNG and capped at 5 MiB. S3 inputs must identify an exact bucket/key and should include s3Version; AWS service limits still apply to S3 object size and image dimensions.
• Idempotency: these five operations do not create Rekognition collections or mutate the input. Repeating the same immutable request has no storage side effect, but it can incur another charge and results may change with provider model versions.
• Billable ambiguity: every analysis is sent exactly once. If transport fails after AWS accepted it, reconcile CloudTrail/request evidence and the immutable input before replaying.
• Destructive behavior: the connector never changes or deletes images, S3 objects, faces, collections, or projects. It sends image data to AWS and initiates billable processing.
• Moderation: threshold selection is a business-policy choice. Lower thresholds produce more candidates for review. Never silently suppress findings solely because confidence is below a universal default.
• Biometrics: confirmBiometricProcessing is an execution guard, not legal consent or policy authorization. Face and celebrity findings require a lawful purpose, least-privilege access, retention controls, and human review. Do not use them alone for identity or access decisions.
• Output shape: results are plain maps and arrays without AWS SDK objects. Bounding boxes use relative width, height, left, and top coordinates.
• Data handling: images and findings may contain personal, biometric, safety, or regulated data. Bind only approved accounts and downstream destinations; never put raw bytes or unrestricted findings into logs.
• Provider verification boundary: deterministic tests cover validation, fixed regional routing, account isolation, inline/S3 source mapping, thresholds, face guards, normalized envelopes, failure retryability, single-attempt billing, redaction, registration, and metadata. Live AWS behavior remains unverified until an authorized Rekognition credential and reviewed image are supplied.
• Functional reference: n8n's AWS Rekognition node exposes image analysis for faces, labels, moderation labels, text, and celebrities from binary bytes or S3. ValkyrAI preserves that functional surface while adding immutable S3 versions, strict byte validation, normalized findings, verified account enforcement, biometric confirmation, deterministic attempts, and conservative replay behavior.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsRekognitionModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS S3 ExecModule
• AWS Lambda ExecModule
• AWS DynamoDB ExecModule
• AWS Textract ExecModule
• n8n AWS Rekognition reference
• Amazon Rekognition Image operations
• Integration Account Console