Skip to main content
POST
/
tts
/
stream
Streaming Text-to-Speech
curl --request POST \
  --url https://api.example.com/tts/stream \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "language": "<string>",
  "chunk_size": 123,
  "api_key": "<string>"
}
'

​
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.

​
Request Body

​
text
string
required
The text to convert to speech
​
language
string
default:"en"
Language code (e.g., “en”, “es”, “fr”)
​
chunk_size
number
default:"200"
Number of characters per chunk. Smaller chunks provide faster initial response but more network overhead.
​
api_key
string
required
Your GistMag API key

​
Example Request

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

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

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);
Streaming is ideal for long-form content where you want to start playback immediately rather than waiting for the entire audio to be generated.