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

# Text-to-Speech with Background Music

> Generate speech with background music

## Overview

Generate speech with background music. The music is automatically adjusted in volume, looped to match the speech length, and faded in/out for a professional sound.

<Endpoint method="post" url="/tts/with-music" />

## Request Body

This endpoint uses `multipart/form-data` for file uploads.

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

<ParamField body="music" type="file" required>
  Background music file (MP3, WAV, or other audio format)
</ParamField>

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

<ParamField body="pause_duration" type="number" default="800">
  Pause duration in milliseconds between text segments
</ParamField>

<ParamField body="music_volume" type="number" default="-20">
  Music volume adjustment in decibels. Negative values make music quieter (recommended: -20 to -30)
</ParamField>

<ParamField body="fade_duration" type="number" default="2000">
  Fade in/out duration in milliseconds for the background music
</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/with-music \
  -F "text=This is a narration with background music." \
  -F "music=@background.mp3" \
  -F "language=en" \
  -F "pause_duration=800" \
  -F "music_volume=-20" \
  -F "fade_duration=2000" \
  -F "api_key=your_api_key_here" \
  --output output_with_music.mp3
```

## Response

The response is an MP3 audio file with speech overlaid on background music.

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

**Content-Disposition**: `attachment; filename=output_with_music.mp3`

## Credit Cost

**1 credit per 1,000 characters** (TTS) **+ 1 credit** (background music), with a **minimum of 2 credits** total.

### Examples:

* 10 characters + music = **2 credits** (1 TTS minimum + 1 music)
* 500 characters + music = **2 credits** (1 TTS minimum + 1 music)
* 1,000 characters + music = **2 credits** (1 TTS + 1 music)
* 2,500 characters + music = **4 credits** (3 TTS + 1 music)

## Example Usage

### Python

```python theme={null}
import requests

with open("background.mp3", "rb") as f:
    files = {"music": f}
    data = {
        "text": "This is a narration with background music.",
        "language": "en",
        "pause_duration": 800,
        "music_volume": -20,
        "fade_duration": 2000,
        "api_key": "your_api_key_here"
    }
    
    response = requests.post(
        "https://api.gistmag.co.uk/tts/with-music",
        files=files,
        data=data
    )

with open("output_with_music.mp3", "wb") as f:
    f.write(response.content)
```

## Adding Music to Existing Audio

To add background music to an existing audio file (not generated by TTS), use the [`/tts/add-music`](/api-reference/tts/add-music) endpoint.

<Info>
  The background music is automatically looped if it's shorter than the speech, and trimmed if it's longer. Volume is adjusted to ensure the speech remains clear and audible.
</Info>