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>"
}
'

import requests

url = "https://api.example.com/tts/stream"

payload = {
    "text": "<string>",
    "language": "<string>",
    "chunk_size": 123,
    "api_key": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({text: '<string>', language: '<string>', chunk_size: 123, api_key: '<string>'})
};

fetch('https://api.example.com/tts/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/tts/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'language' => '<string>',
    'chunk_size' => 123,
    'api_key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/tts/stream"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"chunk_size\": 123,\n  \"api_key\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/tts/stream")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"chunk_size\": 123,\n  \"api_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/tts/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"chunk_size\": 123,\n  \"api_key\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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>"
}
'

import requests

url = "https://api.example.com/tts/stream"

payload = {
    "text": "<string>",
    "language": "<string>",
    "chunk_size": 123,
    "api_key": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({text: '<string>', language: '<string>', chunk_size: 123, api_key: '<string>'})
};

fetch('https://api.example.com/tts/stream', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/tts/stream",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'language' => '<string>',
    'chunk_size' => 123,
    'api_key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/tts/stream"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"chunk_size\": 123,\n  \"api_key\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/tts/stream")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"chunk_size\": 123,\n  \"api_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/tts/stream")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"chunk_size\": 123,\n  \"api_key\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

string

required

The text to convert to speech

string

default:"en"

Language code (e.g., “en”, “es”, “fr”)

number

default:"200"

Number of characters per chunk. Smaller chunks provide faster initial response but more network overhead.

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

Text Splitting: Text is automatically split into chunks at sentence boundaries (., !, ?) to maintain natural speech flow
Sequential Processing: Each chunk is processed independently and converted to speech
Real-time Streaming: Audio chunks are streamed immediately as MP3 (128k bitrate) as soon as they’re generated
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.

Basic Text-to-Speech Batch Text-to-Speech

Overview

Alt Text Generation

Text-to-Speech

Blog Meta Generator

Site Audit

Indexing

Management

Streaming Text-to-Speech

Overview

Request Body

Example Request

Response

Credit Cost

Examples:

How It Works

When to Use Streaming

Example Usage

Python

JavaScript

​Overview

​Request Body

​Example Request

​Response

​Credit Cost

​Examples:

​How It Works

​When to Use Streaming

​Example Usage

​Python

​JavaScript

Overview

Request Body

Example Request

Response

Credit Cost

Examples:

How It Works

When to Use Streaming

Example Usage

Python

JavaScript