Text-to-Speech with Background Music

Generate speech with background music

POST /tts/with-music

Text-to-Speech with Background Music

cURL

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

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

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