API Documentation

Welcome to the API documentation for livelike text-to-speech / text-to-MP3 conversion for ttsMP3.com

Convert any written text into spoken words and get a finished MP3 returned. Use any speaker as known from our main page. Use any language you want.

API access comes for free with every 1-year premium purchase but has to be requested via e-mail.


Table of Contents

1. Synthesize Speech

Request
MethodURL
POST or GEThttps://api.ttsmp3.com/v1/
TypeParamsValues
POST or GETapikeystring
POST or GETspeakerstring
POST or GETtextstring
apikey

apikey must be sent with all client requests. The apikey helps the server to validate the request source.


speaker

The speaker must be a valid speaker as described in 2. Speakers.


Reponse
StatusResponse
200{"status":200,"status_message":"Parsed to engine with positive response","data":{"Error":0,"Speaker":"Joanna","Cached":0,"Text":"this is a testing scenario","Chars":26,"Quota":921949,"URL":"https:\/\/ttsmp3.com\/created_mp3\/4546fbf893ea91a9c03927cd82eda3dc.mp3","MP3":"4546fbf893ea91a9c03927cd82eda3dc.mp3"}}
Your requested text was synthesized and returned with no errors
210{"status":210,"status_message":"Parsed to engine with positive response","data":{"Error":0,"Speaker":"Joanna","Cached":1,"Text":"this is a testing scenario","URL":"https:\/\/ttsmp3.com\/created_mp3\/4546fbf893ea91a9c03927cd82eda3dc.mp3","MP3":"4546fbf893ea91a9c03927cd82eda3dc.mp3"}}
Your requested text hit the cache. It was already synthesized earlier and you will not have any credits deducted for conversion.
300{"status":300,"status_message":"Parsed to engine without a response","data":null}
Your text was sent to the engine, but there was not reponse. Not even a negative one. Most likely the synthesize engine was unreachable.
310{"status":310,"status_message":"Parsed to engine with negative response","data":{"Error":"There is an error in the format of your message. Please take care of opening \"<\" and closing tags \">\"","Speaker":"Joanna","Cached":0,"Text":"brackets are evil <:","Chars":20,"Quota":921249}}
Your text was sent to the engine, but there was a negative response when synthesizing your text. The reason is most likely unescaped special characters that could not be synthesized or brackets like < or > that may be part of wrongly closed SSML-Tags
320{"status":320,"status_message":"Conversion will exceed quota","data":null}
Every account has a preselected quota depending on the plan that was chosen for accessing. If you would exceed the quota converting the given text, this error will occur.
400{"status":400,"status_message":"APIkey missing","data":null}
Your request was sent without an APIKey.
401{"status":401,"status_message":"APIkey is invalid","data":null}
The passed APIKey is invalid.
410{"status":410,"status_message":"Speaker missing","data":null}
Your request was sent without a speaker.
420{"status":420,"status_message":"Text to convert missing","data":null}
Your request was sent without a text to convert

1.1. "Data"-Response

If your speech was sent to the tts-engine you will get an array named "data" returned, containing the following information


NameDescription
ErrorThis is either "0" if there was no error or it contains a brief error description from the engine
SpeakerReturns the speaker that was used for conversion
CachedConfirms if the request has hit the cache, 1=yes, 2=no
TextGives back the input text
CharsThe length of the converted text in characters
QuotaThe quota that is left for use in the account in characters
URLThe full URL to your generated mp3-file on our server
MP3The name of the mp3-File that was generated

2. Speakers

When accessing the API you will have to parse a speaker parameter. The speaker has to be one of the following:

Note: It is not necessary to send the language, the language is given with the speakers name.


SpeakerLanguage
ZeinaArabic
RussellAustralian English
NicoleAustralian English
VitoriaBrazilian Portuguese
CamilaBrazilian Portuguese
RicardoBrazilian Portuguese
EmmaBritish English
BrianBritish English
AmyBritish English
ChantalCanadian French
ConchitaCastilian Spanish
LuciaCastilian Spanish
EnriqueCastilian Spanish
ZhiyuChinese Mandarin
NajaDanish
MadsDanish
RubenDutch
LotteDutch
CelineFrench
LeaFrench
MathieuFrench
HansGerman
VickiGerman
MarleneGerman
DoraIcelandic
KarlIcelandic
AditiIndian English
RaveenaIndian English
BiancaItalian
CarlaItalian
GiorgioItalian
TakumiJapanese
MizukiJapanese
SeoyeonKorean
MiaMexican Spanish
LivNorwegian
JacekPolish
JanPolish
MajaPolish
EwaPolish
CristianoPortuguese
InesPortuguese
CarmenRomanian
MaximRussian
TatyanaRussian
AstridSwedish
FilizTurkish
SalliUS English
IvyUS English
JoeyUS English
MatthewUS English
KimberlyUS English
KendraUS English
JustinUS English
JoannaUS English
LupeUS Spanish
PenelopeUS Spanish
MiguelUS Spanish
GwynethWelsh
GeraintWelsh English

3. Usage Examples

PHP

Since PHP is my primary coding language in web development, i will provide a PHP/HTML example for speech conversion. Feel free to send me more usage examples to support@ttsmp3.com :-)

				POST-Example in PHP
<?php
	$postdata = http_build_query(
		array(
				'apikey' => 'YOUR-API-KEY',
				'speaker' => 'Joanna',
				'text' => 'the quick brown fox jumps over the lazy dog',
			)
		);
	$opts = array('http' =>
		array(
			'method'  => 'POST',
			'header'  => 'Content-type: application/x-www-form-urlencoded',
			'content' => $postdata
		)
	);
	$context  = stream_context_create($opts);
	$result = file_get_contents('https://api.ttsmp3.com/v1/', false, $context);
	$resultarray = json_decode($result, true);
	echo "<pre>".print_r($resultarray, true)."</pre>";

?>
<audio controls>
	<source src="<?php echo $resultarray['data']['URL']; ?>" type="audio/ogg">
</audio>
			

Python (untested)

import requests
import json

# Your API key (replace with your actual API key)
api_key = 'YOUR-API-KEY'

# Data to be sent to the TTS API
postdata = {
	'apikey': api_key,
	'speaker': 'Joanna',
	'text': 'the quick brown fox jumps over the lazy dog',
}

# TTS API endpoint
url = 'https://api.ttsmp3.com/v1/'

# Send the POST request to the TTS API
response = requests.post(url, data=postdata)

# The API response is expected to be in JSON format
result = response.json()

# Pretty-print the result
print(json.dumps(result, indent=4))

# If there's a 'URL' in the response, we can access it as follows
if 'data' in result and 'URL' in result['data']:
	audio_url = result['data']['URL']

	# Save the audio file to the local file system
	audio_response = requests.get(audio_url)
	with open('tts_audio.mp3', 'wb') as audio_file:
		audio_file.write(audio_response.content)
	print(f"Audio file saved as 'tts_audio.mp3'.")
else:
	print("Error: Unable to retrieve the audio URL from the response.")
				

Node.js (untested)

				FIRST "npm install axios"
				
const axios = require('axios');
const fs = require('fs');

// Your API key (replace with your actual API key)
const api_key = 'YOUR-API-KEY';

// Data to be sent to the TTS API
const postdata = {
    'apikey': api_key,
    'speaker': 'Joanna',
    'text': 'the quick brown fox jumps over the lazy dog',
};

// TTS API endpoint
const url = 'https://api.ttsmp3.com/v1/';

// Send the POST request to the TTS API
axios.post(url, new URLSearchParams(postdata))
    .then(response => {
        // The API response is expected to be in JSON format
        console.log(response.data);

        // If there's a 'URL' in the response, we can access it as follows
        if (response.data && response.data.data && response.data.data.URL) {
            const audioUrl = response.data.data.URL;

            // Use the streaming interface to download the file
            axios({
                method: 'get',
                url: audioUrl,
                responseType: 'stream'
            }).then(response => {
                // Create a write stream for the mp3 file
                const audioStream = fs.createWriteStream('tts_audio.mp3');
                
                // Pipe the response data to the file
                response.data.pipe(audioStream);
                
                audioStream.on('finish', () => {
                    console.log('Audio file saved as "tts_audio.mp3"');
                });
            }).catch(error => {
                console.error('Error downloading the audio file:', error);
            });

        } else {
            console.log('Error: Unable to retrieve the audio URL from the response.');
        }
    })
    .catch(error => {
        console.error('Error in API request:', error);
    });
				

Java (untested)

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.HashMap;
import java.util.Map;
import java.util.StringJoiner;

public class ApiPostRequest {

    public static void main(String[] args) throws IOException, InterruptedException {
        String apiKey = "YOUR-API-KEY";
        
        HttpClient client = HttpClient.newHttpClient();
        String url = "https://api.ttsmp3.com/v1/";

        // Data to be sent to the TTS API
        Map<Object, Object> data = new HashMap<>();
        data.put("apikey", apiKey);
        data.put("speaker", "Joanna");
        data.put("text", "the quick brown fox jumps over the lazy dog");

        // Encode the data
        StringJoiner sj = new StringJoiner("&");
        for(Map.Entry<Object, Object> entry: data.entrySet()) {
            sj.add(URLEncoder.encode(entry.getKey().toString(), StandardCharsets.UTF_8) + "="
                 + URLEncoder.encode(entry.getValue().toString(), StandardCharsets.UTF_8));
        }

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Content-Type", "application/x-www-form-urlencoded")
                .POST(HttpRequest.BodyPublishers.ofString(sj.toString()))
                .build();

        HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.body());
    }
}
				

Ruby (untested)

require 'net/http'
require 'uri'
require 'json'

api_key = 'YOUR-API-KEY'
url = URI.parse('https://api.ttsmp3.com/v1/')

# Data to be sent to the TTS API
params = {
  'apikey' => api_key,
  'speaker' => 'Joanna',
  'text' => 'the quick brown fox jumps over the lazy dog',
}

# Create the HTTP objects
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url.request_uri)
request.set_form_data(params)
request["Content-Type"] = "application/x-www-form-urlencoded"

# Send the request
response = http.request(request)

puts JSON.pretty_generate(JSON.parse(response.body))