Skip to main content
PyAI Speak adds natural spoken replies to an app, chatbot or phone agent. Keep your existing language model and application; use Speak for speech output.

Choose the job you want to complete

Keep API keys on your backend. Before using an example, verify the intended project, environment, scopes, limits and billing with GET /v1/me, and agree on a request budget. A streaming request can consume billable usage. Speak converts text into audio with one OpenAI-compatible TTS endpoint:
The canonical model is pyai-speak; the required scope is speak:synthesize. The response is audio bytes, not JSON or a download URL. Save the body to a file or consume it as it arrives. Set up your API key before running the examples.

Synthesize your first clip

Install the version used by the examples below. Speech requests are not automatically retried; check an uncertain result before submitting again:
Success is 200 OK with a WAV body saved as confirmation.wav, at 24 kHz by default. Play it with your audio player. If the request fails, inspect the error body instead of treating the output as audio. Keep input within 2,000 characters. For saved WAV files, use stream: false so RIFF/data lengths describe the complete file. The Python example requires pyai-sdk 0.5.1 or later; the TypeScript 0.18.1 defaults buffered speech calls and CLI file output to complete audio. The explicit flag also keeps this example compatible with older clients; speechStream and CLI stdout remain streaming. Streaming WAV headers may contain unknown-length sentinels; buffering those bytes alone does not finalize the file. Use the streaming examples below when consuming audio incrementally.

Choose a voice from the catalog

Do not hardcode assumptions about voice language, product support, or delivery mode. Read the catalog:
For each row:
  • voice_id is the canonical input.
  • aliases are permanent convenience inputs on the advertised surfaces.
  • available_on tells you whether the voice works on Speak, Omni, or both.
  • synthesis_modes tells you which stream values the voice accepts. Every Speak voice accepts both; an empty list means the voice has no Speak surface at all.
  • speak_emotions lists qualified emotion directions for this voice. An empty or absent list means directed emotion is unavailable.
  • tier and pricing describe the customer-facing quality tier and its catalog treatment. Check the pricing page for current commercial terms.
Designed voices appear in the same catalog with source: "design". Cloned voices are managed separately under /v1/voice/clones.

Natural voices

Natural is a selectable customer-facing voice tier, not a different endpoint:
  • English en1 (canonical id stock_aria_en) works on Speak in both streaming and buffered modes. The same id is available on Omni. It is the only Natural-tier voice in the catalog today; the former Hindi Natural aliases hi5–hi8 are retired. Hindi is served by the Standard-tier voices, which work on both Speak and Omni.
  • Check the pricing page for current voice-tier treatment.
Always inspect the live catalog. available_on is the product contract; synthesis_modes is the delivery contract.

Emotion direction

Emotion support is specific to each voice. Read speak_emotions from GET /v1/voices before sending a direction. When the chosen voice advertises it, pass emotion with happy, sad, angry, fearful, or surprised. This works with both streaming and buffered delivery. Omit the field, or use neutral, for the voice’s ordinary delivery.
A successful directed response includes x-pyai-emotion with the requested name and x-pyai-emotion-applied: true. Unsupported voice/direction combinations return 400 unsupported_parameter; invalid direction names return 400 invalid_emotion. If a qualified direction is temporarily unavailable, Speak returns 503 emotion_unavailable before returning audio. Speak does not offer intensity or free-form instructions controls. Direction describes delivery; keep pacing and check-in questions in the script itself.

Streaming vs buffered delivery

stream defaults to true:
  • Use true when playback should start as bytes arrive.
  • Use false when your client requires a complete body and Content-Length. Every voice advertising Speak support accepts both values. Delivery can still be buffered for a voice or format: x-pyai-stream: buffered means the audio was rendered before delivery. stream: true alone is not proof of incremental playback. MP3 and Opus are buffered formats; use PCM, WAV, or G.711 for a streaming integration and inspect the effective response.

Turn an LLM reply into spoken responses

Audio streaming and text streaming are different. This HTTP endpoint accepts a complete input string per request; it is not a socket for sending individual LLM tokens. For a reply that grows over time, collect a phrase or sentence before submitting it, preserve the order of spoken phrases, and cancel both the active request and queued speech when the user interrupts. Avoid a request per token. The LiveKit and Pipecat guides use the existing framework adapters; your application still owns its conversation and interruption behavior.

Consume bytes as they arrive

An ArrayBuffer read followed by playback demonstrates buffered application behavior even when the server is incremental. Consume the response body and pass each chunk to your audio pipeline as it arrives. Abort a synthesis when the caller interrupts, and do not retry after any audible bytes without a policy for repeated speech.
Node streaming consumption

Input length

input is capped at 2000 characters per request. Longer text answers 400 input_too_long, naming the limit and the length you sent — split the script and concatenate the audio, or use Cast for long-form work, which is built for it.

Output formats and sample rates

For pcm, choose sample_rate from 8 kHz through 48 kHz. G.711 is always 8 kHz; omit sample_rate or pass exactly 8000. A conflicting G.711 sample rate is rejected. The telephony audio reference explains companding, resampling, and the exact format to send to common phone transports. For a complete client with backpressure and cancellation, use the G.711 streaming example.

Stock, cloned, or designed

  • Stock: select a row from GET /v1/voices; no enrollment required.
  • Clone: enroll a voice you have explicit permission to use. See Clone.
  • Design: create a new synthetic voice from a text description with /v1/voice/design, preview candidates, and save one into your voice library.
Voice is biometric data when it represents a real person. Establish consent before cloning; prompt-designed synthetic voices are a separate workflow. Start a design job with a stable idempotency key:
Poll GET /v1/voice/design/{design_id} until candidates are ready, preview their signed URLs, then save one with POST /v1/voice/design/{design_id}/save. Voice design requires speak:design; cloning uses the separate speak:clone scope.

Compatibility and unsupported controls

OpenAI model names are accepted as aliases for pyai-speak: tts-1, tts-1-hd, tts-1-1106, tts-1-hd-1106, and gpt-4o-mini-tts. So are the preset voice names alloy, echo, fable, onyx, nova, and shimmer. An alias is a name and nothing else: it never changes the engine, the lane, or the voice you would otherwise get. New integrations should prefer pyai-speak and canonical catalog voice IDs. speed, seed, and temperature are not active Speak controls. Sending them returns 400 unsupported_parameter; do not assume they were silently applied.

TTS API reference

Exact speech request and audio response contract.

Browse voices

Filter the live catalog and inspect surface/mode support.

Clone

Enroll, test, use, and delete a consented voice.

Telephony audio

PCM and G.711 formats, rates, and resampling.

Language support

Choose a voice that matches the required language and product.

Failure recovery

For calls with several spoken replies, use call-stable TTS recovery. Reuse one speech session ID so recovery cannot change the voice midway through a call.