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

​
Overview

Generate high-quality speech from text using the default voice. This is the simplest way to convert text to speech.

​
Request Body

​
text
string
required
The text to convert to speech
​
language
string
default:"en"
Language code (e.g., “en”, “es”, “fr”). See supported languages
​
voice_name
string
Optional Google Cloud voice name (e.g., en-US-Wavenet-D). Use GET /tts/voices to discover available voices.
​
speed
number
default:"1.0"
Speaking rate. Values < 1.0 slow down the voice, values > 1.0 make it faster.
​
pitch
number
default:"0.0"
Pitch adjustment in semitones. Positive values raise the pitch, negative values lower it.
​
volume_gain_db
number
default:"0.0"
Volume gain in decibels. Range is typically between -96.0 and +16.0.
​
api_key
string
required
Your GistMag API key

​
Example Request

curl -X POST https://api.gistmag.co.uk/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test of the text-to-speech API.",
    "language": "en",
    "voice_name": "en-US-Wavenet-D",
    "speed": 1.0,
    "pitch": 0.0,
    "volume_gain_db": 0.0,
    "api_key": "your_api_key_here"
  }' \
  --output output.wav

​
Response

The response is an audio file (WAV format) with the generated speech. Content-Type: audio/wav Content-Disposition: attachment; filename=output.wav

​
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)
  • 999 characters = 1 credit (minimum charge)
  • 1,000 characters = 1 credit
  • 1,001 characters = 2 credits (rounded up)
  • 2,500 characters = 3 credits (rounded up)
  • 5,000 characters = 5 credits

​
Example Usage

​
Python

import requests

response = requests.post(
        "https://api.gistmag.co.uk/tts",
    json={
        "text": "Hello, this is a test.",
        "language": "en",
        "voice_name": "en-US-Wavenet-D",
        "speed": 1.0,
        "pitch": 0.0,
        "volume_gain_db": 0.0,
        "api_key": "your_api_key_here"
    }
)

with open("output.wav", "wb") as f:
    f.write(response.content)

​
JavaScript

const response = await fetch('https://api.gistmag.co.uk/tts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    text: 'Hello, this is a test.',
    language: 'en',
    voice_name: 'en-US-Wavenet-D',
    speed: 1.0,
    pitch: 0.0,
    volume_gain_db: 0.0,
    api_key: 'your_api_key_here'
  })
});

const audioBlob = await response.blob();
const audioUrl = URL.createObjectURL(audioBlob);
// Play the audio or download it

​
Text Length Limits

  • Maximum: 10,000 characters per request
  • Recommended: For longer text, use the batch endpoint
For very long text, consider using the batch endpoint which automatically splits text into manageable chunks.