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.
| Method | URL |
|---|---|
| POST or GET | https://api.ttsmp3.com/v1/ |
| Type | Params | Values |
|---|---|---|
| POST or GET | apikey | string |
| POST or GET | speaker | string |
| POST or GET | text | string |
apikey must be sent with all client requests. The apikey helps the server to validate the request source.
The speaker must be a valid speaker as described in 2. Speakers.
| Status | Response |
|---|---|
| 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 |
If your speech was sent to the tts-engine you will get an array named "data" returned, containing the following information
| Name | Description |
|---|---|
| Error | This is either "0" if there was no error or it contains a brief error description from the engine |
| Speaker | Returns the speaker that was used for conversion |
| Cached | Confirms if the request has hit the cache, 1=yes, 2=no |
| Text | Gives back the input text |
| Chars | The length of the converted text in characters |
| Quota | The quota that is left for use in the account in characters |
| URL | The full URL to your generated mp3-file on our server |
| MP3 | The name of the mp3-File that was generated |
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.
| Speaker | Language |
|---|---|
| Zeina | Arabic |
| Nicole | Australian English |
| Russell | Australian English |
| Ricardo | Brazilian Portuguese |
| Camila | Brazilian Portuguese |
| Vitoria | Brazilian Portuguese |
| Brian | British English |
| Amy | British English |
| Emma | British English |
| Chantal | Canadian French |
| Enrique | Castilian Spanish |
| Lucia | Castilian Spanish |
| Conchita | Castilian Spanish |
| Zhiyu | Chinese Mandarin |
| Naja | Danish |
| Mads | Danish |
| Ruben | Dutch |
| Lotte | Dutch |
| Mathieu | French |
| Celine | French |
| Lea | French |
| Vicki | German |
| Marlene | German |
| Hans | German |
| Karl | Icelandic |
| Dora | Icelandic |
| Aditi | Indian English |
| Raveena | Indian English |
| Giorgio | Italian |
| Carla | Italian |
| Bianca | Italian |
| Takumi | Japanese |
| Mizuki | Japanese |
| Seoyeon | Korean |
| Mia | Mexican Spanish |
| Liv | Norwegian |
| Jan | Polish |
| Maja | Polish |
| Ewa | Polish |
| Jacek | Polish |
| Cristiano | Portuguese |
| Ines | Portuguese |
| Carmen | Romanian |
| Tatyana | Russian |
| Maxim | Russian |
| Astrid | Swedish |
| Filiz | Turkish |
| Kimberly | US English |
| Ivy | US English |
| Kendra | US English |
| Justin | US English |
| Joey | US English |
| Matthew | US English |
| Salli | US English |
| Joanna | US English |
| Penelope | US Spanish |
| Lupe | US Spanish |
| Miguel | US Spanish |
| Gwyneth | Welsh |
| Geraint | Welsh English |
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>