iSpeech API Specification v1.0

The iSpeech API allows developers to add text to speech capabilities into any web enabled application.

The API's implementation is simple as it uses basic form encoded data (REST) as a communication medium.

Some example code is available for VB.NET, C#, PHP, ActionScript3 (AS3) and HTML implementations.

Working Notes

You must have an API enabled account in order to utilize this API. Any calls with a standard account will result in a failure. Please contact us to enable API access on your existing account.

Valid login credentials must be provided for every request.

An action must be specified with every request.

Request

Every call to the API must contain a username (the email address), a password and an action. Each action has its own requirements. Please refer to each individual action for more information.

Every Request Requires:

Example Request:
uname=email@domain.com&pword=123456&act=information

Each request must be sent to the URL below via the POST method.

http://ws.ispeech.org/api/is_api.php

Response

Every response will include a 'result' variable containing either success or error. Please refer to each individual action for more information.

Example Response:
result=success&credits=13343433

Error Codes

Below is a list of possible error codes and a description for each event.

Code Message Reason Solution
1 Invalid username or password You specified an invalid username or password. Use valid login credentials.
2 Could not add text to queue Internal Error Try posting your text again, or modify it.
3 Not enough credits Your account does not have enough credits for the conversion. Sign in to your account and purchase more word credits.
4 No action specified You didn't specify an action or used and invalid action. Enter a valid action.
5 Invalid text You didn't specify any text to convert. Specify the text to convert.
6 Too many words Occurs when you exceed the allowed maximum words allowed per conversion. Reduce the amount of words sent to be converted.
7 Invalid text entry Your text appeared invalid or contained invalid characters Modify your text and remove invalid characters (only ISO 8859-1 is currently supported)
9 Invalid hash The hash you provided was invalid or was not associated with your account. Specify the correct hash, or attempt a new conversion.
10 File not found or incomplete The file was not done converting or you specified an invalid hash. Check the file status to get an estimated time to completion.
997 No api access Your account does not have API access. Please contact us to enable API access on your existing account.

Actions

Information

Requires:

Optional:

Returns

Currently only returns the amount of word credits your account contains.

Convert

Requires:

Optional:

Returns

Returns the file status, the file hash and the amount of words in the text, which is also the credit cost.

Status

Requires:

Optional:

Returns

Returns the file status, which is: waiting, the file is waiting to be converted, complete the file is complete and can be downloaded, or error the file could not be converted. Also includes the filesize (if available), the amount of words in the file and the estimated time to completion in seconds (eta).

Download

Requires:

Optional:

Returns

Returns the actual file binary data if successful. You can verify if it is an error message or binary data by checking the server response header. An audio file will specify 'audio/mpeg' as the content type.

If the content type is text/plain then an error occurred: