iSpeech API Specification

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. We have tried to make the API as simple to implement as possible. If you encounter a problem or have a question, please do not hesitate to contact us.

Working Notes

You must have a valid API enabled account to utilize this API. Any calls with an invalid account will result in a failure. Please sign up at for an account if you have not already.

Valid credentials must be provided for every request
An action must be passed with every request

Request

Every call to the iSpeech text to speech API must contain a username (the account 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:

username - The account email address
password - The account password
action - The requested action

Example Request:


username=email@domain.com&password=abc123&action=information

Each request must be sent via POST to the following URL:

Note: GET requests do not work.

http://ws.ispeech.org/api/rest/1.5

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=1454524

Error Codes

The following table contains 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	You tried converting the same text in the same format before the conversion completed.	Wait a few minutes and try again.
3	Not enough credits	Your account does not have enough credits for the requested action.	Sign in to your account and purchase more word credits or upgrade your account.
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)
8	Invalid voice	The voice you specified was invalid.	Specify a correct voice value.
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.
11	Invalid fileid	The file identifier you provided was invalid or was not associated with your account.	Specify the correct file identifier, or attempt a new conversion.
12	Invalid file format	The file format you specified was invalid.	Specify a correct file format.
13	Invalid speed	The speed you provided was an invalid value.	Specify a correct speed value
14	Invalid dictionary	The dictionary you specified was invalid or does not exist.	Specify a correct dictionary identifier
997	No api access	Your account does not have API access.	Please contact us to enable API access on your existing account.
1000	Invalid Request Method POST required	You are not using the "POST" method.	You must POST your data to the iSpeech API

Actions

The following actions are currently enabled for this version of the API.

information
convert
status
download

Information

Required Parameters

No parameters are required

Optional Parameters

No optional parameters

Return Values

Returns the amount of word credits currently available to your account.

result - success if the action was completed successfully or error, with an appropriate error code
credits - the amount of credits in account

Convert

Queues text to be converted to speech.

Required Parameters

text - The text to convert to speech

Optional Parameters

voice - The voice to use.
- engfemale1 - A high quality US english female voice.
- engfemale2 - A low quality US english female voice. This voice does not require credits.
- engmale1 - A high quality US english male voice. This is the default voice.
format - The file format of the audio. If you need a specific file format, please contact us.
- aiff - Audio Interchange File Format (16khz, 16bit, mono)
- flac - Free Loseless Audio Codec (16khz, 16bit, mono)
- mp3 - MPEG-1 Audio Layer 3 (48kBPS, 16kHz, Mono) This is the default format.
- mp4 - MPEG-4 Part 14 (33kBPS, 44kHz, Stereo)
- ogg - OGG File Format (48kBPS, 22kHz, Mono)
- vox - VOX File Format (128kBPS, 8kHz, Mono)
- wav - Waveform Audio Format (16kHz, 16bit, Mono)
- wma - Windows Media Audio (48kBPS, 44kHz, Mono)
title - The title of the file.

Defaults to the first thirty characters of your text.

speed - Controls the speed of which the speaker speaks.

Valid values are -10 for very slow to 10 very fast
The default value is 0 for normal speed

callback - This is a URL that will be notified when the conversion process is complete.
- By default, no callback url is used.
- Must be a fully qualified absolute URL (ex: http://www.domain.com/page)
- This URL will only be notified if the return value of status is waiting.
- This URL will be notified via the POST method with the following parameters:

Return Values

Returns the file status, the file identifier and the amount of words in the text, which is also the credit cost (if applicable).

result - success if the action was completed successfully or error, with an appropriate error code
fileid - the file identifier
status - the file status
words - the amount of words in the text

Status

Checks a conversion's status by its file identifier.

Required Parameters

fileid - The file identifier of the file

Optional Parameters

No optional parameters

Return Values

Returns the file conversion status, the file size, the amount words in the file and the estimated time to completion.

result - success if the action was completed successfully or error, with an appropriate error code
status - The status of the file
- waiting - the file is waiting to be converted.
- working - the file is currently being converted.
- finished - the file is converted and can be downloaded.
- failed - the file failed and could not be converted.
filesize - The size of the file in bytes (if available)
words - The amount of words in the text
eta - The estimated time to completion in seconds
format - The file format of this conversion

Download

Downloads the requested audio file. The first download costs no credits, additional downloads of the audio file cost 1 credit per 1,000 words.

Required Parameters

fileid - The file identifier of the file

Optional Parameters

No optional parameters

Return Values

Returns the actual binary data if successful. You can verify the file type via the content-type header of the server response. An audio file will specific audio/format, where format is the file format (mp3, aiff, wav, etc).

A content-type of text/plain will be returned if an error occurred.

result - only error, with an appropriate error code