Text to Speech API¶

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

At a glance¶

• Four Amazon Polly engines — Standard, Neural, Long-Form and Generative, each registered as its own model with its own voice set, see Models.
• 60+ voices across 30+ languages — name a Polly voice ID directly, or send an OpenAI voice name and let one be picked for you, see Feature compatibility.
• Language detected from the first 500 characters — Amazon Comprehend reads that much of the input to choose the voice behind an OpenAI voice name, see Working with Amazon Polly.
• SSML markup accepted — pronunciation, emphasis, pauses and prosody, up to 6,000 characters including the markup, which is not billed, see Working with Amazon Polly.
• Up to 100,000 input characters against OpenAI's 4,096 — 3,000 with no bucket configured, 20,000 on a generative voice, see Long Input.
• instructions is accepted and ignored, speed is rejected with SSML input — see Limits and behaviour to know.

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": "Hello from Amazon Polly."}'

Endpoints¶

Feature compatibility¶

Models¶

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.

Working with Amazon Polly¶

Amazon Polly Features¶

• SSML Support : Fine-grained control over pronunciation, emphasis, pauses, and prosody — SSML docs
• Flexible Formats: mp3, ogg, wav, flac, aac, opus, pcm
• Streaming Options: Raw bytes (default) or SSE events with stream_format: "sse"
• Speed Control: Adjust playback from 0.2x to 4.0x — generative voices speak no faster than 2.0x
• Speech Marks: Word, sentence, viseme, and SSML timing metadata with SpeechMarkTypes (returned as JSON instead of audio)

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

Limits and behaviour to know¶

• instructions is accepted and ignored. Amazon Polly has no equivalent parameter, so the audio comes back as if the field had not been sent — use SSML, or a different voice, to get the delivery you want.
• speed is rejected with SSML input, because SSML carries a speaking rate of its own: set it with <prosody> instead.
• speed runs from 0.2 to 4.0. Above 2.0 a generative voice (amazon.polly-generative) speaks no faster: the request succeeds and the audio is simply no shorter. Every other voice speeds up across the whole range.
• Usage is counted in characters, the native billing unit of Amazon Polly and Amazon Comprehend, rather than in OpenAI-style tokens. No output token count is reported.
• Once an SSE stream is accepted, a synthesis failure can no longer be an HTTP status: it arrives as a terminal error event inside the 200 response, and speech.audio.done is then omitted.
• Input above 3,000 characters needs an S3 bucket unless the voice is generative, and a long request is billed the moment Amazon Polly accepts it — both are detailed under Long Input.

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¶

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"
  }'

Next steps¶

Next: Models API · Speech to Text API · Model aliases for tts-1 and tts-1-hd · Text-to-speech IAM permissions, including long input