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
VitóriaBrazilian Portuguese
RicardoBrazilian Portuguese
CamilaBrazilian Portuguese
AmyBritish English
BrianBritish English
EmmaBritish English
ChantalCanadian French
EnriqueCastilian Spanish
LuciaCastilian Spanish
ConchitaCastilian Spanish
ZhiyuChinese Mandarin
MadsDanish
NajaDanish
RubenDutch
LotteDutch
CélineFrench
LéaFrench
MathieuFrench
VickiGerman
MarleneGerman
HansGerman
DóraIcelandic
KarlIcelandic
RaveenaIndian English
AditiIndian English
GiorgioItalian
CarlaItalian
BiancaItalian
MizukiJapanese
TakumiJapanese
SeoyeonKorean
MiaMexican Spanish
LivNorwegian
JacekPolish
MajaPolish
JanPolish
EwaPolish
InêsPortuguese
CristianoPortuguese
CarmenRomanian
MaximRussian
TatyanaRussian
AstridSwedish
FilizTurkish
JoeyUS English
KimberlyUS English
SalliUS English
IvyUS English
JoannaUS English
MatthewUS English
KendraUS English
JustinUS English
PenélopeUS Spanish
LupeUS 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 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>