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
NicoleAustralian English
RussellAustralian English
RicardoBrazilian Portuguese
VitóriaBrazilian Portuguese
EmmaBritish English
BrianBritish English
AmyBritish English
ChantalCanadian French
ConchitaCastilian Spanish
EnriqueCastilian Spanish
LuciaCastilian Spanish
ZhiyuChinese Mandarin
MadsDanish
NajaDanish
RubenDutch
LotteDutch
CélineFrench
LéaFrench
MathieuFrench
MarleneGerman
VickiGerman
HansGerman
KarlIcelandic
DóraIcelandic
AditiIndian English
RaveenaIndian English
CarlaItalian
BiancaItalian
GiorgioItalian
MizukiJapanese
TakumiJapanese
SeoyeonKorean
MiaMexican Spanish
LivNorwegian
EwaPolish
JanPolish
MajaPolish
JacekPolish
CristianoPortuguese
InêsPortuguese
CarmenRomanian
MaximRussian
TatyanaRussian
AstridSwedish
FilizTurkish
IvyUS English
JoannaUS English
JoeyUS English
JustinUS English
KendraUS English
KimberlyUS English
MatthewUS English
SalliUS English
MiguelUS Spanish
PenélopeUS 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 $result['data']['URL']; ?>" type="audio/ogg">
</audio>