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

# Streaming Text-to-Speech

> Stream audio in real-time as it's generated

## Overview

Stream audio in real-time as it's being generated. This is ideal for live reading applications where you want to start playing audio before the entire text is processed.

<Endpoint method="post" url="/tts/stream" />

## Request Body

<ParamField body="text" type="string" required>
  The text to convert to speech
</ParamField>

<ParamField body="language" type="string" default="en">
  Language code (e.g., "en", "es", "fr")
</ParamField>

<ParamField body="chunk_size" type="number" default="200">
  Number of characters per chunk. Smaller chunks provide faster initial response but more network overhead.
</ParamField>

<ParamField body="api_key" type="string" required>
  Your GistMag API key
</ParamField>

## Example Request

```bash theme={null}
curl -X POST https://api.gistmag.co.uk/tts/stream \
  -H "Content-Type: application/json" \
  -d '{
    "text": "This is a long text that will be streamed in chunks...",
    "language": "en",
    "chunk_size": 200,
    "api_key": "your_api_key_here"
  }' \
  --output stream.mp3
```

## Response

The response is a streaming MP3 audio file. Audio chunks are sent as they're generated.

**Content-Type**: `audio/mpeg`

## Credit Cost

**1 credit per 1,000 characters**, with a **minimum of 1 credit** for any request.

### Examples:

* 10 characters = **1 credit** (minimum charge)
* 500 characters = **1 credit** (minimum charge)
* 1,000 characters = **1 credit**
* 2,500 characters = **3 credits** (rounded up)

**Content-Disposition**: `inline`

## How It Works

1. **Text Splitting**: Text is automatically split into chunks at sentence boundaries (`.`, `!`, `?`) to maintain natural speech flow
2. **Sequential Processing**: Each chunk is processed independently and converted to speech
3. **Real-time Streaming**: Audio chunks are streamed immediately as MP3 (128k bitrate) as soon as they're generated
4. **Low Latency**: Client can start playing audio while remaining chunks are still being generated

## When to Use Streaming

**Use streaming when:**

* You want **low latency** - audio starts playing immediately
* Building **live reading** or **real-time applications**
* Users need to hear audio **as quickly as possible**
* You're okay with receiving multiple audio chunks that need to be combined client-side

**Don't use streaming when:**

* You need a **single complete file** for download
* You want **pauses between segments** (use batch instead)
* You prefer **higher quality audio** (batch uses 192k vs streaming's 128k)

## Example Usage

### Python

```python theme={null}
import requests

response = requests.post(
        "https://api.gistmag.co.uk/tts/stream",
    json={
        "text": "This is a long text...",
        "language": "en",
        "chunk_size": 200,
        "api_key": "your_api_key_here"
    },
    stream=True
)

with open("stream.mp3", "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)
```

### JavaScript

```javascript theme={null}
const response = await fetch('https://api.gistmag.co.uk/tts/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'This is a long text...',
    language: 'en',
    chunk_size: 200,
    api_key: 'your_api_key_here'
  })
});

const reader = response.body.getReader();
const chunks = [];

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  chunks.push(value);
}

// Combine chunks and play
const audioBlob = new Blob(chunks, { type: 'audio/mpeg' });
const audioUrl = URL.createObjectURL(audioBlob);
```

<Info>
  Streaming is ideal for long-form content where you want to start playback immediately rather than waiting for the entire audio to be generated.
</Info>