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>"
}
'

import requests

url = "https://api.example.com/tts/with-music"

payload = {
    "text": "<string>",
    "language": "<string>",
    "pause_duration": 123,
    "music_volume": 123,
    "fade_duration": 123,
    "api_key": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: '<string>',
    language: '<string>',
    pause_duration: 123,
    music_volume: 123,
    fade_duration: 123,
    api_key: '<string>'
  })
};

fetch('https://api.example.com/tts/with-music', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/tts/with-music",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'language' => '<string>',
    'pause_duration' => 123,
    'music_volume' => 123,
    'fade_duration' => 123,
    'api_key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/tts/with-music"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"pause_duration\": 123,\n  \"music_volume\": 123,\n  \"fade_duration\": 123,\n  \"api_key\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/tts/with-music")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"pause_duration\": 123,\n  \"music_volume\": 123,\n  \"fade_duration\": 123,\n  \"api_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/tts/with-music")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"pause_duration\": 123,\n  \"music_volume\": 123,\n  \"fade_duration\": 123,\n  \"api_key\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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>"
}
'

import requests

url = "https://api.example.com/tts/with-music"

payload = {
    "text": "<string>",
    "language": "<string>",
    "pause_duration": 123,
    "music_volume": 123,
    "fade_duration": 123,
    "api_key": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: '<string>',
    language: '<string>',
    pause_duration: 123,
    music_volume: 123,
    fade_duration: 123,
    api_key: '<string>'
  })
};

fetch('https://api.example.com/tts/with-music', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/tts/with-music",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'text' => '<string>',
    'language' => '<string>',
    'pause_duration' => 123,
    'music_volume' => 123,
    'fade_duration' => 123,
    'api_key' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/tts/with-music"

	payload := strings.NewReader("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"pause_duration\": 123,\n  \"music_volume\": 123,\n  \"fade_duration\": 123,\n  \"api_key\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/tts/with-music")
  .header("Content-Type", "application/json")
  .body("{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"pause_duration\": 123,\n  \"music_volume\": 123,\n  \"fade_duration\": 123,\n  \"api_key\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/tts/with-music")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"text\": \"<string>\",\n  \"language\": \"<string>\",\n  \"pause_duration\": 123,\n  \"music_volume\": 123,\n  \"fade_duration\": 123,\n  \"api_key\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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.

string

required

The text to convert to speech

file

required

Background music file (MP3, WAV, or other audio format)

string

default:"en"

Language code (e.g., “en”, “es”, “fr”)

number

default:"800"

Pause duration in milliseconds between text segments

number

default:"-20"

Music volume adjustment in decibels. Negative values make music quieter (recommended: -20 to -30)

number

default:"2000"

Fade in/out duration in milliseconds for the background music

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.

Batch Text-to-Speech Speech-to-Text

Overview

Alt Text Generation

Text-to-Speech

Blog Meta Generator

Site Audit

Indexing

Management

Text-to-Speech with Background Music

Overview

Request Body

Example Request

Response

Credit Cost

Examples:

Example Usage

Python

Adding Music to Existing Audio

​Overview

​Request Body

​Example Request

​Response

​Credit Cost

​Examples:

​Example Usage

​Python

​Adding Music to Existing Audio

Overview

Request Body

Example Request

Response

Credit Cost

Examples:

Example Usage

Python

Adding Music to Existing Audio