If you've never used the service before, we recommend taking a quick look at our Getting Started page so that you can be using the API within minutes.
The API Gateway is available at this URL:
The current version of the API is 1. If there are ever any future API updates, they will be hosted with a different URI so your application can continue to use the exact API version that it was developed for.
The gateway will accept both HTTP GET and POST requests.
API Authentication and Security
The API supports both public keys and HMAC authentication.
Public Key method
The public key method is fine for testing and development. When sending a request to the service, include your API key as a parameter. For example:
HMAC authentication method
We recommend using HMAC authentication in production environments, where your API key is never transmitted over the network. We recommend that all developers use this method. This method involves 4 steps:
- Construct your request URI as you normally would: http://api.ttsengine.com/v1/tts?text=example
- Append your App ID to the end of the URI: http://api.ttsengine.com/v1/tts?text=example&appid=abcdef0123456789
Calculate the MD5 hash (hmac) of your request with your key appended to it: (Request + Key)
i.e. md5( http://api.ttsengine.com/v1/tts?text=example&appid=abcdef0123456789ghijkl9876543210 ) → API key
Append the hash value (with the name hmac) to the end of your URI:
When this request is received the hmac value is validated against your key from our database so your key is never included in the transmission.
If you've used the public key method above we recommend that you generate new API keys before upgrading to HMAC authentication.
API Languages and Voices
You can use a HTTP GET request to query what languages or voices are available.
http://api.ttsengine.com/v1/tts/languages will return a list of the available languages
http://api.ttsengine.com/v1/tts/voices?language=usenglish will return a list of the available voices for the specified language.
As with any API the request should be URI encoded.
|text||This should contain the text to be read.||test|
|language||(OPTIONAL) The language of the given text. If this parameter is not supplied, usenglish is assumed. The section above describes how to obtain the list of available languages.|
|voice||(OPTIONAL) The name of the voice to be used. If this parameter is not specified the default voice for the selected language will be used. The section above describes how to obtain the list of available voices for any language.|
|format||The file format of the synthesized speech. This should be ogg, mp3, or wav||mp3|
|key||The user's API Key||abcdef0123456789|
|appid||The user's APP ID||abcdef|
|hmac||A valid hash of the HTTP GET URI (see the API Security section).||abcdef0123456789|
API Error Codes
The API uses 7 standard HTTP error codes to explain problems. In the case of request errors, a clear explanation of the error is always included in the response body. We recommend that developers examine the response body (not just the error code) when debugging a problem.
|HTTP Status Code||Explanation|
|400||General user error, the response body will explain in more detail, it can be any of the following: Bad voice option, Text not specified, URI no longer active (in the case of an expired callback URI). Word limit exceeded. Text limit exceeded.|
|401||Unauthorized. This error will happen if the request contains an invalid Key, App ID or HMAC.|
|402||Payment required. This error will happen if there are not enough credits to perform this request.|
|415||This error indicates that either the format or rate options contained an invalid value.|
|500||Internal server error|
|503||Service temporarily unavailable|
- Eclipse/JSP SDK (Version 1.1)
- Visual Studio/ASP SDK