Skip to content

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?

  • Global Support
    30+ languages supported. Choose from Neural, Generative, and Long-Form engines.

  • 60+ Voices
    Professional narration to conversational voices. Use OpenAI voice names with automatic language detection or specify any Polly voice ID directly.

  • Automatic Language Detection
    Using OpenAI voice names? Amazon Comprehend automatically detects your content's language and selects an appropriate Polly voice—matching language, gender, and quality.

  • Advanced Control with SSML
    Fine-tune pronunciation, emphasis, pauses, and prosody with SSML markup for complex audio requirements.

Quick Start: Available Endpoint

Endpoint Method What It Does Powered By MCP Tool
/v1/audio/speech POST Turn text into natural-sounding speech Amazon Polly + Amazon Comprehend openai_audio_speech

Feature Compatibility

Feature Status Notes
Voice Selection
OpenAI voice names Mapped to Polly voices
Polly voice IDs 60+ voices across 30+ languages
Dynamic voice selection Select best Polly voice based on the detected language
Input
Plain text Standard text input
SSML markup Fine-grained speech control
Output Formats
MP3 Native Polly format
PCM 24 kHz per OpenAI's contract; resampled from Polly's native rate
Opus Native Polly format
AAC Encoded from PCM
FLAC Encoded from PCM
WAV Encoded from PCM
OGG (Vorbis) Native Polly format
Control
speed parameter 0.2x to 2.0x playback speed; rejected with SSML input (set the speed in SSML instead)
instructions parameter Accepted for OpenAI API compatibility and ignored (no Amazon Polly equivalent)
Extra model-specific params Extra model-specific parameters via JSON body
Streaming
Byte streaming Default streaming mode
SSE streaming Event-based streaming
Usage tracking
Input text tokens Characters count (billing unit)
Output tokens Not available

Legend:

  • Supported — Fully compatible with OpenAI API
  • Extra Feature — Enhanced capability beyond OpenAI API
  • Unsupported — Not available in this implementation

Model Support

Amazon Polly Amazon Polly Models

Model Polly Engine Notes
amazon.polly-standard Standard Lowest cost, widest language coverage
amazon.polly-neural Neural Higher-quality, natural-sounding voices
amazon.polly-long-form Long-form Expressive voices for narration-length content
amazon.polly-generative Generative Most human-like, conversational voices

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.

OpenAI Model Compatibility

stdapi.ai includes built-in model aliases that map OpenAI model names to Amazon Polly engines:

  • tts-1amazon.polly-standard
  • tts-1-hdamazon.polly-neural

These aliases enable seamless compatibility with OpenAI-based tools and applications without any configuration changes. You can also customize or override these aliases to suit your needs.

Advanced Features

Amazon Polly 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

Performance Tips: Optimize Speed & Cost

  • Prefer mp3 or ogg for the lowest latency; pcm is returned at OpenAI's 24 kHz contract unless you request an explicit SampleRate (see Sample Rate)
  • Specify a Polly voice ID to bypass language detection—faster responses, no Amazon Comprehend charges
  • Configure a default language via DEFAULT_TTS_LANGUAGE environment variable to skip language detection for all requests using OpenAI voice names

Language Detection Behavior

When using OpenAI voice names without specifying a default language, the system analyzes only the first 500 characters of your text to detect the language. This approach:

  • Works best with long, single-language texts where the first 500 characters are representative
  • May be inconsistent with very short texts (< 100 characters) where language detection has limited context
  • Can produce mixed results with multi-language content where different parts use different languages

For consistent behavior across requests, consider:

  • Setting DEFAULT_TTS_LANGUAGE for applications serving primarily one language
  • Using Polly voice IDs directly when you know the target language
  • Structuring multi-language applications to make separate API calls per language

Default Streaming Mode: API vs MCP

  • API usage: Default is byte streaming (raw audio data)
  • MCP tool usage: Default is SSE streaming (stream_format: "sse")

When used as an MCP tool, the response defaults to SSE events (speech.audio.delta, speech.audio.done) for better client compatibility. Override by explicitly setting stream_format: "audio" in your request.

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

PCM output defaults to OpenAI's 24 kHz contract

Per OpenAI's TTS API, response_format: "pcm" is raw, headerless 24 kHz 16-bit mono little-endian audio. Without an explicit SampleRate, pcm output is synthesized by Polly at 16 kHz and resampled to 24 kHz server-side. Pass a Polly-native SampleRate (8000 or 16000) to skip resampling and receive Polly's raw rate instead — since raw PCM carries no embedded rate, only do this when your client knows to play it back at that rate.

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

Speech marks return JSON, not audio

When SpeechMarkTypes is set, Polly returns timing metadata only. The response is a stream of JSON objects (one per line) with the application/x-json-stream content type:

  • response_format is ignored — no audio is returned.
  • stream_format: "sse" is rejected with HTTP 400, since the payload is not audio events.
  • The ssml mark type requires SSML input (<speak>…</speak>); requesting it with plain text returns HTTP 400.
{"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.