Text to Speech API¶

Generate natural-sounding speech from text with Amazon Polly through an OpenAI-compatible interface.

Why Choose the Text to Speech API?¶

Available Endpoints¶

Feature Compatibility¶

Model Support¶

Amazon Polly Models¶

Each engine supports a different subset of voices and languages — see the Polly voice list for details. OpenAI voice names work with every model through automatic language detection and voice selection, or specify any Polly voice ID directly for 60+ voices across 30+ languages.

Advanced Features¶

Amazon Polly Features¶

• SSML Support : Fine-grained control over pronunciation, emphasis, pauses, and prosody — SSML docs. With SSML input, the speed parameter is rejected: set the speaking rate with SSML <prosody> instead.
• Flexible Formats: mp3, ogg, wav, flac, aac, opus, pcm
• Streaming Options: Raw bytes (default) or SSE events with stream_format: "sse" — once an SSE stream is accepted, a synthesis failure at any point is reported as a terminal error event inside the 200 response, and speech.audio.done is then omitted
• Speed Control: Adjust playback from 0.2x to 2.0x
• Speech Marks: Word, sentence, viseme, and SSML timing metadata with SpeechMarkTypes (returned as JSON instead of audio)
• Character-Based Billing: Usage tracks character counts—the native billing unit for Amazon Polly and Amazon Comprehend—rather than OpenAI-style tokens

Long Input¶

A single request accepts up to 3,000 characters (6,000 including SSML markup, which is not billed). Beyond that, how the audio is produced depends on the voice.

Generative voices (amazon.polly-generative) speak up to 20,000 characters without any further configuration, and the audio starts arriving while the rest is still being spoken. Two cases keep the behaviour described below instead: an input written as an SSML document, and a request using SpeechMarkTypes.

Every other voice, and generative input longer than 20,000 characters, is synthesized into an S3 bucket co-located with the serving region, so longer input requires a bucket in a region that can serve the request: a AWS_S3_REGIONAL_BUCKETS entry for that region, or AWS_S3_BUCKET when the region is the first AWS_BEDROCK_REGIONS entry — the only region AWS_S3_BUCKET covers. With AWS_POLLY_REGION pinned to any other region, a regional-bucket entry is the only option. The audio object is written under AWS_S3_TMP_PREFIX and deleted once the request ends. On a request that ends before Amazon Polly has finished — a timeout, a failure, or a client that disconnected — the deletion is issued while the synthesis is still running, so an object written after it is not removed by the request: the recommended lifecycle rule on that prefix is what expires it, and it must be in place.

• With a bucket configured: up to 100,000 characters (200,000 including SSML markup), against OpenAI's 4,096-character limit. Expect roughly one extra second per 1,000 characters, bounded by AI_RESPONSE_TIMEOUT.
• Without one: a generative voice still speaks up to 20,000 characters; every other request above 3,000 characters is rejected, however long, with the length the server does accept — so callers can split their text.

Provider-Specific Parameters¶

Unlock advanced Amazon Polly capabilities by passing provider-specific parameters directly in your requests. These parameters are forwarded to Polly's SynthesizeSpeech API and allow you to access features unique to Polly.

How It Works:

Add provider-specific fields at the top level of your request body alongside standard OpenAI parameters. The API automatically forwards these to Amazon Polly.

Examples:

Lexicon Support:

Apply custom pronunciation lexicons to your speech synthesis:

{
  "model": "amazon.polly-neural",
  "voice": "Joanna",
  "input": "Amazon Polly uses lexicons for custom pronunciation.",
  "response_format": "mp3",
  "LexiconNames": ["MyCustomLexicon"]
}

Sample Rate:

Specify custom audio sample rate (8000, 16000, 22050, or 24000 Hz; PCM output supports 8000 and 16000 only):

{
  "model": "amazon.polly-neural",
  "voice": "Matthew",
  "input": "High quality audio at 24kHz.",
  "response_format": "mp3",
  "SampleRate": "24000"
}

Language Code:

Specify the language for bilingual voices (only useful for voices that support multiple languages):

{
  "model": "amazon.polly-neural",
  "voice": "Aditi",
  "input": "Hello, how are you?",
  "response_format": "mp3",
  "LanguageCode": "en-IN"
}

Speech Marks:

Request word, sentence, viseme, or SSML timing marks instead of audio (useful for lip-sync, karaoke-style highlighting, or subtitle alignment):

{
  "model": "amazon.polly-neural",
  "voice": "Joanna",
  "input": "Hello, how are you?",
  "SpeechMarkTypes": ["word", "sentence"]
}

{"time":0,"type":"word","start":0,"end":5,"value":"Hello"}
{"time":576,"type":"word","start":7,"end":10,"value":"how"}

Configuration Options:

Option 1: Per-Request

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

Option 2: Server-Wide Defaults

Configure default parameters for specific models via the DEFAULT_MODEL_PARAMS environment variable:

export DEFAULT_MODEL_PARAMS='{
  "amazon.polly-neural": {
    "SampleRate": "24000"
  }
}'

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

Behavior:

Compatible parameters are forwarded to Polly and applied; unsupported parameters return HTTP 400 with an error message.

Available Parameters:

The following parameters from the Amazon Polly SynthesizeSpeech API can be used:

• LexiconNames (list): Apply pronunciation lexicons
• SampleRate (string): Audio sample rate in Hz — 8000, 16000, 22050, or 24000 (pcm output: 8000 or 16000; omit it to get OpenAI's 24 kHz pcm contract instead)
• LanguageCode (string): Language code for bilingual voices only (e.g., en-IN, hi-IN)
• SpeechMarkTypes (list): Timing marks to return instead of audio — sentence, ssml, viseme, word

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 text to synthesize; the audio produced from it is not itself evaluated. X-Amzn-Bedrock-Trace is accepted but has no effect on this route — no guardrail trace is returned.

Example with headers:

curl -X POST "$BASE/v1/audio/speech" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Amzn-Bedrock-GuardrailIdentifier: your-guardrail-id" \
  -H "X-Amzn-Bedrock-GuardrailVersion: 1" \
  -d '{
    "model": "amazon.polly-neural",
    "voice": "Amy",
    "input": "Welcome to the future of voice technology!"
  }' \
  --output speech.mp3

Try It Now¶

Stream audio as bytes (default):

curl -OJ -X POST "$BASE/v1/audio/speech" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.polly-neural",
    "voice": "Amy",
    "input": "Welcome to the future of voice technology!",
    "response_format": "mp3"
  }'

Stream audio as SSE events:

curl -N -X POST "$BASE/v1/audio/speech" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "amazon.polly-neural",
    "voice": "Amy",
    "input": "This audio streams as SSE events!",
    "response_format": "mp3",
    "stream_format": "sse"
  }'

Ready to add voice to your application? Explore available voices and models in the Models API.