Skip to main content
POST
/
tts
/
with-music
Text-to-Speech with Background Music
curl --request POST \
  --url https://api.example.com/tts/with-music \
  --header 'Content-Type: application/json' \
  --data '
{
  "text": "<string>",
  "language": "<string>",
  "pause_duration": 123,
  "music_volume": 123,
  "fade_duration": 123,
  "api_key": "<string>"
}
'

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

​
Request Body

This endpoint uses multipart/form-data for file uploads.
​
text
string
required
The text to convert to speech
​
music
file
required
Background music file (MP3, WAV, or other audio format)
​
language
string
default:"en"
Language code (e.g., “en”, “es”, “fr”)
​
pause_duration
number
default:"800"
Pause duration in milliseconds between text segments
​
music_volume
number
default:"-20"
Music volume adjustment in decibels. Negative values make music quieter (recommended: -20 to -30)
​
fade_duration
number
default:"2000"
Fade in/out duration in milliseconds for the background music
​
api_key
string
required
Your GistMag API key

​
Example Request

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

​
Example Usage

​
Python

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)

​
Voice Cloning with Music

For voice cloning with background music, use the /tts/with-music/voice-clone endpoint.

​
Adding Music to Existing Audio

To add background music to an existing audio file (not generated by TTS), use the /tts/add-music endpoint.
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.