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

# Basic Text-to-Speech

> Convert text to speech

## Overview

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

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

## 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"). See [supported languages](/api-reference/tts/introduction#supported-languages)
</ParamField>

<ParamField body="voice_name" type="string" optional>
  Optional Google Cloud voice name (e.g., `en-US-Wavenet-D`). Use [`GET /tts/voices`](/api-reference/tts/voices) to discover available voices.
</ParamField>

<ParamField body="speed" type="number" default="1.0">
  Speaking rate. Values \< 1.0 slow down the voice, values > 1.0 make it faster.
</ParamField>

<ParamField body="pitch" type="number" default="0.0">
  Pitch adjustment in semitones. Positive values raise the pitch, negative values lower it.
</ParamField>

<ParamField body="volume_gain_db" type="number" default="0.0">
  Volume gain in decibels. Range is typically between -96.0 and +16.0.
</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 \
  -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

```python theme={null}
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

```javascript theme={null}
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](/api-reference/tts/batch)

<Info>
  For very long text, consider using the batch endpoint which automatically splits text into manageable chunks.
</Info>