AWS Transcribe ExecModule

Overview

AwsTranscribeModule brings Amazon Transcribe batch speech-to-text jobs into ValkyrAI workflows. It covers n8n's create, get, list, and delete transcription-job lifecycle while adding strict S3 source validation, verified IntegrationAccount credentials, bounded pagination, safe read-only retries, single-attempt mutations, language identification, speaker diarization, channel identification, alternatives, custom vocabularies, PII redaction, job tags, explicit deletion confirmation, and annotation-backed Workflow Studio discovery.

The connector implements four operations:

• start_transcription_job submits an S3 audio or video object for asynchronous transcription.
• get_transcription_job retrieves one job, status, failure evidence, and transcript locations.
• list_transcription_jobs retrieves one or more bounded pages of job summaries.
• delete_transcription_job removes a Transcribe job only after explicit confirmation.

The module starts provider jobs and reports provider transcript locations. It does not download transcript files, modify source media, or claim that speech recognition is error-free. Review transcripts before using them for customer, employment, financial, medical, safety, identity, or access decisions.

Usage

1. Store the exact audio or video object in an approved S3 bucket.
2. Create a dedicated AWS IAM principal with only the Transcribe actions and exact S3 permissions required by the workflow.
3. Store its access key ID and secret access key in an AWS IntegrationAccount, verify it, and keep it in READY status.
4. Bind the account through ExecModuleConfig.authConfig.integrationAccount and select an exact AWS region.
5. Start a job with a unique jobName, exact s3:// mediaUri, and either a known languageCode or identifyLanguage: true.
6. Preserve the unique name and returned requestId; poll with get_transcription_job until the status is COMPLETED or FAILED.
7. Fetch transcript bytes through a separately authorized S3/HTTP step only after validating the returned location and data-handling policy.

Never put AWS keys into module input, media URIs, 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 four documented operations.
region	string	Every execution	None	AWS region syntax such as us-west-2; custom endpoints are not accepted.
jobName	string	Start, get, delete	None	1-200 letters, digits, ., _, or -; unique and case-sensitive for start.
mediaUri	string	Start	None	Exact s3://bucket/object URI; bucket must be DNS-compatible and object key at most 1,024 UTF-8 bytes.
languageCode	string	Start with known language	None	Provider code such as en-US; mutually exclusive with automatic identification.
identifyLanguage	boolean	Start with unknown language	false	Exactly one of this flag or languageCode is required.
mediaFormat	string	Optional start	Provider detection	amr, flac, m4a, mp3, mp4, ogg, wav, or webm.
mediaSampleRateHertz	integer	Optional start	Provider detection	8,000-48,000; when supplied it must match the source.
outputBucketName	string	Optional start	Service-managed output	Exact DNS-compatible bucket.
outputKey	string	Optional start	Job-name-derived path	At most 1,024 UTF-8 bytes; requires outputBucketName.
vocabularyName	string	Optional start	None	Existing custom vocabulary name, 1-200 safe characters.
showSpeakerLabels	boolean	Optional start	false	Enables speaker diarization; requires maxSpeakerLabels.
maxSpeakerLabels	integer	Diarization	None	2-30; requires showSpeakerLabels: true.
channelIdentification	boolean	Optional start	false	Mutually exclusive with speaker diarization.
showAlternatives	boolean	Optional start	false	Requires maxAlternatives.
maxAlternatives	integer	Alternative transcripts	None	2-10; requires showAlternatives: true.
redactPii	boolean	Optional start	false	Enables provider PII redaction.
redactionOutput	string	PII redaction	redacted	redacted or redacted_and_unredacted.
piiEntityTypes	array	PII redaction	["ALL"]	Unique supported types; ALL must stand alone.
tags	object	Optional start	None	1-50 non-secret string pairs; reserved aws: keys are rejected.
jobNameContains	string	Optional list filter	None	Same safe-character and 200-character bound as a job name.
jobStatus	string	Optional list filter	None	QUEUED, IN_PROGRESS, FAILED, or COMPLETED.
nextToken	string	Optional list resume	None	Opaque token from the preceding result.
limit	integer	List	100	1-10,000 total returned summaries.
returnAll	boolean	List	false	Follows provider pages until exhaustion, limit, or the 100-page guard.
confirmDelete	boolean	Delete	false	Must be exactly true before provider deletion.

Supported PII types are BANK_ACCOUNT_NUMBER, BANK_ROUTING, CREDIT_DEBIT_NUMBER, CREDIT_DEBIT_CVV, CREDIT_DEBIT_EXPIRY, PIN, EMAIL, ADDRESS, NAME, PHONE, SSN, and ALL.

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, including safe get/list retries.
data	object	Start, get, or delete success	Normalized job or deletion result.
items	array	List success	Bounded job summaries ordered by the provider.
count	integer	List success	Number of returned summaries.
pages	integer	List success	Provider pages consumed.
hasMore	boolean	List success	Whether another provider page remains.
nextToken	string	Another page remains	Opaque continuation token.
jobStatus	string	Start/get success	QUEUED, IN_PROGRESS, FAILED, COMPLETED, or a future provider value.
transcriptUri	string	Completed unredacted job	Provider S3 or temporary service-managed transcript location.
redactedTranscriptUri	string	Completed redacted job	Redacted transcript location.
failureReason	string	Failed job	Bounded provider job failure reason.
requestId	string	AWS supplies one	Bounded provider reference for reconciliation and support.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Job data can include jobName, jobStatus, language evidence, media format/sample rate, source URI, transcript locations, failure reason, provider timestamps, and returned job tags. Treat every media/transcript URI and all speech-derived metadata as confidential workflow data.

IntegrationAccount Requirements

Bind one AWS IntegrationAccount through the normalized ExecModule authentication relationship:

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

Grant only the selected actions:

• transcribe:StartTranscriptionJob
• transcribe:GetTranscriptionJob
• transcribe:ListTranscriptionJobs
• transcribe:DeleteTranscriptionJob only for workflows that need deletion
• s3:GetObject on exact approved input objects
• s3:PutObject on the exact output prefix when outputBucketName is used
• the minimum KMS permissions for encrypted S3 media or output, when applicable

The current connector supports a long-lived access-key pair. Temporary session credentials, role assumption, custom endpoints, streaming transcription, Transcribe Medical, Medical Scribe, Call Analytics, custom-language-model management, vocabulary management, vocabulary filters, subtitle output, toxicity detection, and transcript-byte download are deferred.

Configuration

The awsAccount relationship is the only credential configuration. Job identity, media, language, transcription features, pagination, and deletion confirmation belong in mapped input; safe read retries use the normalized retry policy.

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:aws-transcribe-production"
  },
  "retryPolicy": {
    "maxAttempts": 3
  },
  "payloadConfig": {
    "parameters": "{\"operation\":\"start_transcription_job\",\"region\":\"us-west-2\",\"languageCode\":\"en-US\"}"
  }
}

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

Operations

Operation	Provider behavior	Side effect and retry behavior
start_transcription_job	Starts one asynchronous batch transcription from S3.	Billable external processing; exactly one provider attempt. Reconcile ambiguity by unique job name.
get_transcription_job	Reads one job and transcript/failure evidence.	Read-only; transient failures retry within policy.
list_transcription_jobs	Reads filtered job summaries with bounded pagination.	Read-only; each page can retry within policy.
delete_transcription_job	Permanently removes provider job metadata.	Destructive; requires confirmation and exactly one provider attempt.

Deleting a Transcribe job does not delete its S3 source or customer-bucket output object. It can remove service-managed job discovery/evidence, so preserve required audit data before deletion.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing job/media/language, malformed region or S3 URI, incompatible audio options, invalid tags/filter/bounds, or missing delete 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_TRANSCRIBE_HTTP_400	Invalid audio, language, format, sample rate, output, or feature combination.	Usually no	Validate the immutable object and request parameters.
AWS_TRANSCRIBE_HTTP_403	IAM denies Transcribe, S3, or KMS access.	No	Grant only the missing action on the exact resource.
AWS_TRANSCRIBE_HTTP_409	A start reused an existing job name.	No automatic replay	Read the existing job and reconcile its source/config before choosing another name.
AWS_TRANSCRIBE_HTTP_429 / 500 / 503	Throttle, concurrency quota, or transient provider pressure.	Only get/list auto-retry	Reconcile start/delete outcomes before any manual replay.
NETWORK_ERROR	DNS, TLS, timeout, or connectivity failure.	Only get/list auto-retry	Treat mutations as ambiguous and search by the unique job name.
EXECUTION_ERROR	Unexpected bounded runtime failure.	No automatic replay	Preserve the operation, region, job name, immutable media reference, and request evidence.

Transport/provider exception text is never copied into output, preventing credential echoes and unbounded provider payloads. A FAILED asynchronous job is a successful job read with jobStatus: FAILED and bounded failureReason; it is not silently resubmitted.

Example

Start a redacted, two-speaker support-call transcription:

{
  "operation": "start_transcription_job",
  "region": "us-west-2",
  "jobName": "support-call-1042",
  "mediaUri": "s3://reviewed-call-audio/2026/call-1042.wav",
  "languageCode": "en-US",
  "mediaFormat": "wav",
  "showSpeakerLabels": true,
  "maxSpeakerLabels": 2,
  "redactPii": true,
  "redactionOutput": "redacted",
  "piiEntityTypes": ["ALL"],
  "tags": {
    "workflow": "support-quality",
    "retention": "reviewed"
  }
}

Expected result shape:

{
  "status": "success",
  "operation": "start_transcription_job",
  "attempts": 1,
  "jobStatus": "IN_PROGRESS",
  "requestId": "aws-request-reference",
  "data": {
    "jobName": "support-call-1042",
    "jobStatus": "IN_PROGRESS",
    "languageCode": "en-US",
    "mediaFormat": "wav",
    "mediaUri": "s3://reviewed-call-audio/2026/call-1042.wav"
  }
}

After the job completes, call get_transcription_job with the same job name. A successful redacted job can then expose redactedTranscriptUri; the workflow should validate and fetch it through an authorized downstream connector.

Notes

• Pagination: list_transcription_jobs requests at most 100 summaries per provider call. returnAll=true follows pages until exhaustion, limit, or 100 pages. If a bound stops traversal, hasMore remains true and nextToken is returned for deterministic resumption.
• Rate limits: quotas vary by operation, account, and region. Get/list operations honor RetryPolicy.maxAttempts from 1 through 5 for throttling and transient failures. AWS SDK retries are disabled so module attempt accounting stays deterministic.
• API limits: job names are capped at 200 characters, media sample rate at 8,000-48,000 Hz, list pages at 100, accumulated summaries at 10,000, and S3 keys/output keys at 1,024 UTF-8 bytes. AWS file-size, duration, format, channel, concurrent-job, and regional limits still apply.
• Idempotency: Amazon Transcribe start has no caller token in this lifecycle. The unique jobName is the reconciliation key. The connector makes one start attempt; on an ambiguous result, get/list that exact name before considering another start.
• Destructive behavior: deletion requires confirmDelete: true and is sent once. The module never deletes S3 input or output objects.
• Output locations: when no customer output bucket is supplied, AWS can return a temporary service-managed transcript URI. Do not persist, email, or publish signed query parameters; consume the location through an authorized workflow step.
• PII redaction: provider redaction reduces exposure but does not prove all sensitive speech was removed. Review redacted transcripts before broader sharing, and avoid redacted_and_unredacted unless the workflow is explicitly authorized for both outputs.
• Accuracy: accents, noise, domain terms, crosstalk, speaker overlap, and model changes affect results. A transcript is machine-generated evidence and should not be the sole source for high-impact decisions.
• Data handling: audio, transcripts, job names, tags, and transcript locations may contain personal or regulated data. Use exact buckets, least privilege, encryption, retention limits, and approved downstream destinations.
• Provider verification boundary: deterministic tests cover validation, fixed regional routing, verified account isolation, S3-only media, language choice, settings coupling, redaction/tags, bounded pagination, safe-read retry, single-attempt mutations, deletion confirmation, response normalization, credential redaction, metadata, and registration. Live AWS execution remains unverified until an authorized Transcribe credential and reviewed S3 media object are supplied.
• Functional reference: n8n's AWS Transcribe node exposes create, get, list, and delete transcription jobs. ValkyrAI keeps that lifecycle while adding verified account enforcement, strict source and option bounds, conservative mutation replay, explicit destructive confirmation, normalized outputs, and annotation-backed catalog metadata.
• Runtime boundary: merged source and published documentation do not update the deployed Workflow Studio catalog until a ValkyrAI backend release exposes AwsTranscribeModule through /v1/modules/metadata.

Related Documentation

• ExecModule catalog
• AWS S3 ExecModule
• AWS Textract ExecModule
• AWS Rekognition ExecModule
• n8n AWS Transcribe reference
• Amazon Transcribe batch jobs
• Amazon Transcribe API
• Integration Account Console