Text To Speech (Speak)

Synthesize speech

OpenAI-compatible text-to-speech. Returns audio bytes. The serving adapter defaults to incremental delivery from the streaming lane. Set stream: false when you require a complete buffered body with Content-Length. Requires the speak:synthesize scope.

post/v1/audio/speech

Request

  • Base URL: https://api.pyai.com
  • URL: https://api.pyai.com/v1/audio/speech
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

modelstring

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

inputstring 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.

voicestring

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'wav' | 'mp3' | 'opus' | 'aac' | 'flac' | 'pcm' | 'g711_ulaw' | 'g711_alaw'

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.

sample_rateinteger

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).

speednumber

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

emotion'neutral' | 'happy' | 'sad' | 'angry' | 'fearful' | 'surprised'

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.

streamboolean

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.

seedinteger

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

temperaturenumber

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).

Changes

No recorded changes to this operation across all 1 revision of this API.