> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Speak text-to-speech

> Choose a voice, synthesize streaming or buffered audio, select an output format, and move cleanly into telephony, cloning, or voice design.

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

```text theme={null}
POST /v1/audio/speech
```

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

## Synthesize your first clip

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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](/reference/telephony-audio) 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](/guides/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:

```bash theme={null}
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.

<CardGroup cols={2}>
  <Card title="Browse voices" href="/api-reference">Filter the live catalog and inspect surface/mode support.</Card>
  <Card title="Voice cloning" href="/guides/voice-cloning">Enroll, test, use, and delete a consented voice.</Card>
  <Card title="Telephony audio" href="/reference/telephony-audio">PCM and G.711 formats, rates, and resampling.</Card>
  <Card title="Language support" href="/reference/language-support">Choose a voice that matches the required language and product.</Card>
</CardGroup>