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?¶

Quick Start: Available Endpoint¶

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

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

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.