Skip to main content
POST
Synthesize speech

Authorizations

Authorization
string
header
required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Body

application/json
input
string
required

Text to synthesize. Maximum 2000 characters; longer text answers 400 input_too_long naming the limit and the length you sent. Split longer scripts into several requests.

Maximum string length: 2000
model
string
default:pyai-speak

Use pyai-speak. The OpenAI tts-1 and tts-1-hd aliases remain accepted for drop-in compatibility.

voice
string

A stock voice id from GET /v1/voices (e.g. stock_dorit_en_us) or a cloned voice id (e.g. voice_abc) created via /v1/voice/clones. Omit to use the platform default voice (stock_dorit_en_us). For drop-in OpenAI compatibility, the preset names alloy, echo, fable, onyx, nova, and shimmer are also accepted and map to PyAI stock voices.

response_format
enum<string>
default:wav

Output audio format. The response Content-Type varies by format (audio/wav, audio/mpeg, audio/ogg, audio/aac, audio/flac, audio/pcm, audio/basic). pcm returns raw, headerless 16-bit little-endian mono samples (no container) at sample_rate, the format voice-agent orchestrators (e.g. Vapi custom-voice, LiveKit/Pipecat) feed directly into their pipelines. g711_ulaw/g711_alaw return raw, headerless G.711 telephony audio at a fixed 8 kHz mono (for Twilio/Plivo/FreeSWITCH); sample_rate does not apply and is rejected unless set to 8000.

Available options:
wav,
mp3,
opus,
aac,
flac,
pcm,
g711_ulaw,
g711_alaw
sample_rate
integer

Optional output sample rate in Hz (8000-48000), e.g. 8000/16000 for telephony or 24000 for wideband. Omit to use the native 24 kHz. Most relevant with response_format: pcm. Does not apply to g711_ulaw/g711_alaw, which are always 8 kHz mono (a conflicting value is rejected).

Required range: 8000 <= x <= 48000
speed
number

Reserved but not active on Speak. Sending this field currently returns 400 unsupported_parameter.

emotion
string

Optional emotion for voices that support expressive rendering (cloned voices and the multilingual natural tier): one of neutral, happy, sad, angry, fearful, surprised. The emotion is rendered in the same voice. Voices that do not support it reject the field with unsupported_parameter. Intensity is not exposed on Speak; use Cast for graded intensity.

stream
boolean
default:true

Use incremental audio delivery. The default is true: the adapter forwards validated chunks as they arrive. Set false to use the blocking lane and receive a complete buffered body with a Content-Length. Every catalog voice accepts both values. A voice whose serving fleet has no streaming lane is rendered on the blocking lane and the response carries x-pyai-stream: buffered — same body, same format, higher time-to-first-byte.

seed
integer

Reserved but not active on Speak. Sending this field currently returns 400 unsupported_parameter.

temperature
number

Reserved but not active on Speak. Sending this field currently returns 400 unsupported_parameter.

Response

Audio bytes. Bytes are delivered incrementally by default; stream: false returns a complete buffered body. The Content-Type varies by response_format: audio/wav (wav), audio/mpeg (mp3), audio/ogg (opus), audio/aac (aac), audio/flac (flac), audio/pcm (pcm, raw/headerless), and audio/basic (g711_ulaw/g711_alaw, raw/headerless G.711 at 8 kHz mono).

The response is of type file.