Speech to Text API¶

Transcribe audio to text with Amazon Transcribe or Amazon Bedrock audio-capable models through an OpenAI-compatible interface.

Why Choose the Speech to Text API?¶

Available Endpoints¶

Feature Compatibility¶

Model Support¶

Amazon Models¶

Mistral Models¶

Amazon Nova Sonic¶

Name this model to transcribe through Amazon Nova Sonic instead of Amazon Transcribe. It is the cheapest transcription option (about $0.006 per minute of audio at current Amazon Bedrock rates) and returns punctuated text in the language that was spoken. Transcription is model selection, never automatic: requests that do not name this model are unaffected.

Other Amazon Bedrock Models¶

Any Amazon Bedrock model that accepts the SPEECH input modality through the Converse API can transcribe out of the box: the gateway sends the audio together with a transcription prompt and returns the model's text output.

Advanced Features¶

Amazon Transcribe Features¶

Model & Features:

• Use amazon.transcribe with the same interface as OpenAI's Whisper API
• Or use OpenAI model names directly: whisper-1, gpt-transcribe, gpt-live-transcribe, gpt-4o-transcribe, and gpt-4o-mini-transcribe work out of the box (they map to amazon.transcribe)
• Auto-detect language or specify it for faster processing, or list the expected languages with languages for multi-language audio
• Word-level or segment-level timestamps with verbose_json
• Speaker Diarization : Automatically identify and label different speakers with diarized_json
• Native Subtitles : SRT/VTT files generated directly by Amazon Transcribe with precise timing

Note: With amazon.transcribe, the prompt, temperature, keywords, and include parameters are rejected with an error to ensure consistent transcription accuracy (for keywords, the error points at the pre-created custom vocabulary alternative via the VocabularyName extra parameter). The known_speaker_names and known_speaker_references parameters are accepted but ignored for every model: Amazon Transcribe's automatic speaker diarization runs without known speaker references, falling back to generic speaker labels.

Provider-Specific Parameters¶

Unlock advanced Amazon Transcribe capabilities by passing provider-specific parameters directly in your request body. These parameters are forwarded to Transcribe's StartTranscriptionJob API.

PII Redaction:

Redact personally identifiable information from the transcript (only the single-output redacted mode is supported):

{
  "model": "amazon.transcribe",
  "file": "data:audio/mp3;base64,<base64-encoded-audio>",
  "ContentRedaction": {
    "RedactionType": "PII",
    "PiiEntityTypes": ["NAME", "SSN", "CREDIT_DEBIT_NUMBER"]
  }
}

Custom Vocabulary and Filtering:

Improve recognition of domain-specific terms and mask or remove profanity/sensitive words:

{
  "model": "amazon.transcribe",
  "file": "data:audio/mp3;base64,<base64-encoded-audio>",
  "VocabularyName": "MyCustomVocabulary",
  "VocabularyFilterName": "MyProfanityFilter",
  "VocabularyFilterMethod": "mask"
}

Alternative Transcriptions and Channel Identification:

Request multiple candidate transcriptions per segment, or transcribe each audio channel separately (e.g. two-party phone calls recorded in stereo):

{
  "model": "amazon.transcribe",
  "file": "data:audio/mp3;base64,<base64-encoded-audio>",
  "ShowAlternatives": true,
  "MaxAlternatives": 3,
  "ChannelIdentification": true
}

Toxicity Detection:

Flag toxic content (profanity, hate speech, harassment) in the transcript:

{
  "model": "amazon.transcribe",
  "file": "data:audio/mp3;base64,<base64-encoded-audio>",
  "ToxicityDetection": [{"ToxicityCategories": ["ALL"]}]
}

Multi-Language Identification:

Detect and transcribe multiple languages spoken in the same audio, optionally restricted to a candidate list:

{
  "model": "amazon.transcribe",
  "file": "data:audio/mp3;base64,<base64-encoded-audio>",
  "IdentifyMultipleLanguages": true,
  "LanguageOptions": ["en-US", "es-US", "fr-FR"]
}

Per-Language Custom Resources:

A custom vocabulary, vocabulary filter or custom language model can only be attached per candidate language when the language is identified rather than given. Pair LanguageIdSettings with LanguageOptions so the dialect your resources were created for is the one identified:

{
  "model": "amazon.transcribe",
  "file": "data:audio/mp3;base64,<base64-encoded-audio>",
  "LanguageOptions": ["en-US", "es-US"],
  "LanguageIdSettings": {
    "en-US": {"VocabularyName": "MedicalTermsEnUs"},
    "es-US": {"VocabularyName": "MedicalTermsEsUs"}
  }
}

Configuration Options:

Option 1: Per-Request

Add provider-specific parameters directly in your JSON request body (as shown in examples above).

Option 2: Server-Wide Defaults

Configure default parameters for amazon.transcribe via the DEFAULT_MODEL_PARAMS environment variable:

export DEFAULT_MODEL_PARAMS='{
  "amazon.transcribe": {
    "VocabularyFilterName": "MyProfanityFilter",
    "VocabularyFilterMethod": "mask"
  }
}'

Note: Per-request parameters override server-wide defaults.

Behavior:

Compatible parameters are forwarded to Amazon Transcribe and applied; unsupported parameters or values return HTTP 400 with an error message.

Available Parameters:

The following parameters from Amazon Transcribe's StartTranscriptionJob API can be used:

• ContentRedaction (object): PII redaction — RedactionType (PII), PiiEntityTypes (list), RedactionOutput (redacted only; redacted_and_unredacted is rejected — the unredacted copy is not tracked for automatic cleanup)
• VocabularyName (string): Custom vocabulary to improve recognition accuracy
• VocabularyFilterName / VocabularyFilterMethod (string / mask, remove, tag): Profanity or sensitive-word filtering
• ShowAlternatives / MaxAlternatives (bool / integer 2-10): Return multiple candidate transcriptions per segment
• ChannelIdentification (bool): Transcribe each audio channel separately (incompatible with diarized_json)
• MaxSpeakerLabels (integer 2-30): Maximum speakers to identify with response_format=diarized_json (default 10)
• ShowSpeakerLabels (bool): Always on with response_format=diarized_json; setting it directly with another format runs AWS speaker labeling without exposing speaker data in the response
• ToxicityDetection (list): Toxic-content flagging — [{"ToxicityCategories": ["ALL"]}]
• IdentifyMultipleLanguages / LanguageOptions (bool / list): Multi-language identification, optionally restricted to a candidate list (supersedes language; cannot be combined with the standard languages parameter)
• LanguageIdSettings (object): Per-language VocabularyName, VocabularyFilterName and LanguageModelName, keyed by language code (up to five) — the only way to attach them when the language is identified rather than given
• ModelSettings (object): LanguageModelName — custom language model selection

VocabularyName, VocabularyFilterName, and custom language models must already exist in your AWS account (created via the AWS Transcribe console, CLI, or SDK) before being referenced here.

Streaming¶

stream=true returns the transcript as server-sent events — transcript.text.delta events followed by a final transcript.text.done — instead of one response body. A ready-to-run example is below.

Each phrase is sent as it is recognized, rather than after the whole recording, whenever the request names the language to expect: send language, or two or more expected languages. That path needs no S3 bucket, so a deployment with no storage configured serves streamed transcriptions.

A request naming neither is still streamed, but its events arrive together once the recording has been read and its language detected. Operators can set AWS_TRANSCRIBE_STREAM_LANGUAGES to the languages their callers actually send, which gives those requests the faster path too. The same applies to a request using any provider-specific parameter above other than VocabularyName, VocabularyFilterName and VocabularyFilterMethod, which are the only ones a phrase-by-phrase transcript can carry.

Streamed events carry text only, which is why srt, vtt and diarized_json are rejected with stream=true rather than answered without their cues or speaker labels.

Available Request Headers¶

This endpoint supports standard Bedrock headers for enhanced control over your requests. All headers are optional and can be combined as needed.

Content Safety (Guardrails)¶

The guardrail evaluates the transcript the model produced, not the audio sent. On a streamed request the events are withheld until the transcript is complete, so the guardrail sees the whole text before any of it is delivered. X-Amzn-Bedrock-Trace is accepted but has no effect on this route — no guardrail trace is returned.

Performance Optimization¶

Both apply only to models transcribed through the Amazon Bedrock runtime. They have no effect on amazon.transcribe, which is served by Amazon Transcribe, nor on Amazon Nova Sonic, which is served over its own bidirectional stream.

Example with headers:

curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id" \
  -H "X-Amzn-Bedrock-GuardrailVersion: 1" \
  -F file=@meeting-recording.mp3 \
  -F model=amazon.transcribe \
  -F response_format=json

Try It Now¶

Transcribe audio to JSON:

curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file=@meeting-recording.mp3 \
  -F model=amazon.transcribe \
  -F response_format=json

Transcribe via JSON body (MCP and AI agents):

When using MCP tools or HTTP clients that cannot construct multipart requests, pass the audio as a data URI or URL:

# Data URI (inline base64)
curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "data:audio/mp3;base64,<base64-encoded-audio>",
    "model": "amazon.transcribe",
    "response_format": "json"
  }'

# HTTPS URL (server fetches the audio)
curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "https://example.com/audio.mp3",
    "model": "amazon.transcribe"
  }'

# Files API reference (file-id: URI scheme)
curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "file-id:file-0190c51c7de7455d9b8c2efe27dfbf67",
    "model": "amazon.transcribe"
  }'

See Files API → Referencing Uploaded Files for the full description of the file-id: URI scheme.

Generate subtitles:

curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file=@video-audio.mp3 \
  -F model=amazon.transcribe \
  -F response_format=srt \
  -F language=en

Transcribe with speaker diarization:

curl -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file=@meeting-recording.mp3 \
  -F model=amazon.transcribe \
  -F response_format=diarized_json

Stream a transcription as SSE events:

Set stream=true to receive the transcript incrementally as server-sent events (transcript.text.delta events followed by a final transcript.text.done event):

curl -N -X POST "$BASE/v1/audio/transcriptions" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F file=@meeting-recording.mp3 \
  -F model=amazon.transcribe \
  -F language=en \
  -F stream=true

Ready to transcribe audio? Explore available transcription models in the Models API.