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.

model
string
default:pyai-voice
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 account's default voice. 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:mp3

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
default:1
stream
boolean
default:false

Opt into incremental audio delivery. When true, the adapter uses the engine streaming lane and forwards each validated chunk as it arrives. When omitted or false, it uses the blocking synthesis lane and preserves the original complete-body response behavior.

seed
integer

Optional determinism seed for reproducible eval runs. Forwarded to the engine and honored once the engine supports it; no effect when omitted.

temperature
number

Optional sampling temperature for reproducible eval runs. Forwarded to the engine and honored once the engine supports it; no effect when omitted.

Response

Audio bytes. With stream: true, bytes are delivered incrementally as the engine produces them; otherwise the complete body is returned after synthesis. 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.