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

# Batch

> Convert text to an audio file with the Plivo Text-to-Speech batch API.

> [!NOTE]
>
> Send text and a voice, get the complete audio back in the reply. Choose raw PCM, WAV, MP3, or 8 kHz μ-law and A-law for phone calls.

Batch turns text into a complete audio file in one request. For audio that starts playing while you are still sending text, use [realtime](https://plivo.com/docs/models/text-to-speech/api/realtime.md).

***

## Synthesize Speech

Convert text to speech and return the audio in the response body.

```text theme={null}
POST https://api.plivo.com/v1/Account/{auth_id}/TTS/
```

### Arguments

Send a JSON body (`Content-Type: application/json`). Leave out a field instead of sending `null`: a `null` returns `422`.

**voice\_id** `string` *required*

A voice from [List voices](https://plivo.com/docs/models/text-to-speech/api/voices.md).

**text** `string` *required*

Text to speak. Up to 5,000 characters.

**language** `string` (default: auto)

`auto`, `en-US`, `en-GB`, `en-IN`, `en-AU`, `hi`, `bn`, `ta`, `te`, `mr`, `gu` or `kn`. The voice must speak it, or the request returns `400 language_not_supported`. There is no plain `en`.

**output\_format** `object`

Audio format. Default: raw `pcm_s16le` at 24000 Hz. See [Output format](#output-format).

**pace** `number` (default: 1.0)

Speaking speed, `0.7` to `1.2`.

**volume** `number` (default: 1.0)

Loudness, `0.5` to `2.0`.

**pronunciations** `array`

Up to 100 inline rules: `{"word", "value", "kind"}`. `kind` is `ipa`, `arpa` or `respell`. See [Pronunciation](https://plivo.com/docs/models/text-to-speech/concepts/pronunciation.md).

**lexicon\_id** `string`

A saved [lexicon](https://plivo.com/docs/models/text-to-speech/api/lexicons.md) to apply.

**continuation** `boolean`

Send `false`, with `seed`, for repeatable audio.

**seed** `integer`

With `continuation: false`, the same input and seed give identical audio.

### Output format

**output\_format.container** `string` (default: raw)

`raw`, `wav` or `mp3`.

**output\_format.encoding** `string` (default: pcm\_s16le)

`pcm_s16le`, `pcm_mulaw`, `pcm_alaw`, or `mp3` for the MP3 container.

**output\_format.sample\_rate** `integer` (default: 24000)

Sample rate in Hz.

**output\_format.bitrate** `integer`

MP3 only, and required for MP3. Bits per second, for example `128000`.

| Use | `container` | `encoding` | `sample_rate` |
| - | - | - | - |
| Phone call (US / India) | `raw` | `pcm_mulaw` | `8000` |
| Phone call (Europe) | `raw` | `pcm_alaw` | `8000` |
| Wideband agent / web | `raw` or `wav` | `pcm_s16le` | `16000` or `24000` |
| Download / playback | `mp3` | `mp3` | `44100` |

```bash cURL (WAV) theme={null}
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/TTS/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "<voice_id>", "text": "Hello from Plivo", "language": "en-US",
       "output_format": {"container": "wav", "encoding": "pcm_s16le", "sample_rate": 24000}}' \
  -o out.wav
```

```bash cURL (phone audio) theme={null}
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/TTS/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "<voice_id>", "text": "Your order ships tomorrow.",
       "output_format": {"container": "raw", "encoding": "pcm_mulaw", "sample_rate": 8000}}' \
  -o out.ulaw
```

```bash cURL (MP3) theme={null}
curl -X POST "https://api.plivo.com/v1/Account/<auth_id>/TTS/" \
  -u '<auth_id>:<auth_token>' \
  -H "Content-Type: application/json" \
  -d '{"voice_id": "<voice_id>", "text": "Hello from Plivo",
       "output_format": {"container": "mp3", "encoding": "mp3", "sample_rate": 44100, "bitrate": 128000}}' \
  -o out.mp3
```

### Response

Returns `200` with the audio as the body. `Content-Type` is `application/octet-stream` (raw), `audio/wav` or `audio/mpeg`.

On error, returns a JSON body. See [Errors](https://plivo.com/docs/models/text-to-speech/troubleshooting/errors.md).
