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
enum<string>

Optional named delivery direction, rendered in the same voice in streaming or buffered mode. Inspect the voice's speak_emotions in GET /v1/voices; an empty or absent list means directed emotion is unavailable. Unsupported voice/emotion combinations return 400 unsupported_parameter. neutral preserves ordinary delivery on every voice. An unavailable emotional rendering returns an error instead of a neutral replacement. Intensity and free-form instructions are not supported on Speak; supplying either returns 400 unsupported_parameter.

Available options:
neutral,
happy,
sad,
angry,
fearful,
surprised
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.

speech_session_id
string

Call-stable voice recovery (enabled organizations and supported stock voices only). Send the same unique call ID and voice on every utterance and retry. The engine is selected before the first audio response and cannot change for this call. Sessions last at most 24 hours; never reuse a call ID. A backup voice may differ from the requested stock voice, but stays fixed for the whole call. Recovery audio is buffered and reports x-pyai-speech-profile: recovery. Omit this field for ordinary synthesis without external voice recovery. Directed emotions and custom/cloned voices are not eligible.

Required string length: 1 - 128
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.