Speak text-to-speech

Speak turns text into audio with one OpenAI-compatible endpoint:

POST /v1/audio/speech

The canonical model is pyai-speak; the required scope is speak:synthesize.

Synthesize your first clip

curl https://api.pyai.com/v1/audio/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pyai-speak",
    "input": "Your appointment is confirmed for Thursday at two.",
    "voice": "stock_dorit_en_us",
    "response_format": "wav"
  }' \
  --output confirmation.wav

The default response is WAV at the voice’s native 24 kHz. Audio bytes are delivered incrementally by default.

Choose a voice from the catalog

Do not hardcode assumptions about voice language, product support, or delivery mode. Read the catalog:

curl "https://api.pyai.com/v1/voices?language=en&source=stock" \
  -H "Authorization: Bearer $PYAI_API_KEY"

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 whether streaming and/or buffered synthesis is supported.
tier and pricing describe the customer-facing quality tier and any voice-specific amount above the base product rate.

Designed voices appear in the same catalog with source: "design". Cloned voices are managed separately under /v1/voice/clones.

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.
If a catalog row advertises only synthesis_modes: ["async"], send stream: false; retrying it on the streaming lane will not make it compatible.

curl https://api.pyai.com/v1/audio/speech \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "This response is returned as one complete file.",
    "voice": "stock_dorit_en_us",
    "response_format": "mp3",
    "stream": false
  }' \
  --output complete.mp3

Output formats and sample rates

Format	Output	Typical use
`wav`	WAV container, 24 kHz default	General playback and files
`mp3`, `opus`, `aac`, `flac`	Encoded audio	Storage and distribution
`pcm`	Raw headerless PCM16 little-endian mono	Realtime frameworks and custom pipelines
`g711_ulaw`, `g711_alaw`	Raw headerless G.711, fixed 8 kHz mono	Phone networks and media streams

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.

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 Voice cloning.
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:

curl https://api.pyai.com/v1/voice/design \
  -H "Authorization: Bearer $PYAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-voice-v1" \
  -d '{
    "prompt": "A calm, clear support voice with measured pacing.",
    "candidates": 3,
    "sample_text": "Thanks for calling. How can I help?"
  }'

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 aliases tts-1 and tts-1-hd, plus the preset names alloy, echo, fable, onyx, nova, and shimmer, remain accepted for drop-in compatibility. 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.

Browse voices

Filter the live catalog and inspect surface/mode support.

Voice cloning

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.

Get started

Omni

Hear

Speak & Cast

Calls & intelligence

Frameworks

Integrations

Use cases

Reference

Synthesize your first clip

Choose a voice from the catalog

Streaming vs buffered delivery

Output formats and sample rates

Stock, cloned, or designed

Compatibility and unsupported controls

Browse voices

Voice cloning

Telephony audio

Language support

​Synthesize your first clip

​Choose a voice from the catalog

​Streaming vs buffered delivery

​Output formats and sample rates

​Stock, cloned, or designed

​Compatibility and unsupported controls

Browse voices

Voice cloning

Telephony audio

Language support

Synthesize your first clip

Choose a voice from the catalog

Streaming vs buffered delivery

Output formats and sample rates

Stock, cloned, or designed

Compatibility and unsupported controls