Text to Speech (TTS) : Speech Recognition (ASR) : API SDK Online

iSpeech API Specification Version 2.0

The iSpeech API allows developers to implement Text-To-Speech (TTS) and Automated Voice Recognition (ASR) in any Internet enabled application.

The API's are platform agnostic which means any device that can record or play audio and is connected to the Internet can use the iSpeech API.

General Working Notes

The API accepts standard HTTP requests in XML, JSON or URL-encoded formats for easy integration in your favorite development language.

Every request must have a valid API key. To obtain an API key please visit our sign up page.

All requests must be sent to:

• URL Encoded:	api.ispeech.org/api/rest
  XML:	api.ispeech.org/api/xml
  JSON:	api.ispeech.org/api/json

The root node for XML requests is "data".

All API calls are synchronous.

HTTP POST must be used for XML or JSON requests, GET request will fail with an error code.

An action must be specified with every request.

The API may be accessed via HTTP or HTTPS (SSL) connections.

You can make a request in XML and receive a response in JSON or URL encoding by specifying the output parameter to JSON, XML, or REST.

Text-To-Speech API

The iSpeech Text-To-Speech API allows you to create high quality speech audio in multiple formats, including mp3, wav, wma, mp4, ogg, flac. The iSpeech API is fast enough to not require call-back URL's. This means you'll always receive audio data or an error message in the same request.

Since the Text-To-Speech API is so easy to use, we provide this very simple one-line quick start. Simply change the API key in the URL to your API key, and you'll receive an mp3 containing the text you specified: http://api.ispeech.org/api/rest?apikey=YOURAPIKEYHERE&action=convert&text=Your+url+encoded+text

Actions

All actions return a result value with either success or error. If the result value is error and appropriate error code and message will be returned in the request. Also, a "202 Accepted" response will be issued along with the error result.

The following actions are available for the text to speech API.

• information
• convert

Information

Required Parameters:

• None

Optional Parameters:

• None

Response Values:

• credits

  integer value

  Amount of credits in account

Example Response:

• result=success&credits=1234

Convert

Required Parameters:

• text	The text to convert to speech

Optional Parameters:

• voice	The voice to use	usenglishfemale1
  format	The file format of the audio file	mp3
  speed	An integer value -10 (slowest) to 10	0
  bitrate	MP3 format Only. A valid bitrate	32
  frequency	MP3 format Only. A valid frequency	16000
  startpadding	Adds silence to start of audio	0
  endpadding	Adds silence to end of audio	0

Response Values:

Returns a HTTP "200 OK" containing the binary audio data on success. If you receive a "202 Accepted", parse the response for an error message.

Speech Recognition API

The iSpeech Automated Speech Recognition API allows you to specify simple word list based grammars or freeform dictation.

Due to the complexity of the Speech Recognition API, we highly recommend using the appropriate language SDK instead of writing your own custom implementation.

Note: You must specify the audio content type in your request. URL encoded requests must past only audio data in their POST. Your requested URL must contain your API key and any other parameters.

The following actions are available for the text to speech API.

• recognize

Recognize

Required Parameters:

• audio: Base64 encoded audio data (XML/JSON only)
• freeform: An integer value for the following:
• • 0 Grammar/Commands
  • 1 Freeform SMS

Required Grammar/Commands Parameters:

• alias A pipe ("|") separated list of commands and aliases.

• Commands must be prefixed with the label 'command'. Any command or alias can refer to any other command or alias by referring to its name wrapped in percent symbols (%).

• You can have multiple commands per alias by separating them with a pipe ("|")

• Examples are in XML format for clarity.

• Example 1:

• <data>
<alias>command1MyCustomCommand</alias>
<command1MyCustomCommand>say yes</command1MyCustomCommand>
</data>
  

  If a user speaks "say yes" it will be successfully recognized.

• Example 2:

• <data>
<alias>command1MyCustomCommand|names</alias>
<command1MyCustomCommand>call %names%</command1MyCustomCommand>
<names>john|mary|anna</names>
</data>
  

  If a user speaks "call john" or "call anna" or "call mary" it will be successfully recognized.

Response Values:

• text A string containing the recognized text This field may be blank
• confidence A double value containing the confidence of the recognition A valid value from 0.0 to 1.0

Example Response:

result=success&text=say+yes&confidence=0.89235

Error Codes

If something goes wrong, you'll receive an error message along with an error code, below is a chart containing the possible error codes.

Example error response:

result=error&code=1&message=Invalid+api+key

• 1	Invalid api key
  2	Could not convert text
  3	Not enough credits
  4	No action specified
  5	Invalid text
  6	Too many words
  7	Invalid text entry
  8	Invalid voice
  12	Invalid file format
  13	Invalid speed
  14	Invalid dictionary
  15	Invalid bitrate
  16	Invalid frequency
  17	Invalid alias list
  18	Alias missing
  19	Invalid content type
  20	Alias list too complex
  21	Could not recognize
  30	Option not enabled for your account. Please contact iSpeech sales at +1 (917) 338-7723 or at sales@ispeech.org to modify your license.
  997	No api access
  998	Unsupported output type
  999	Invalid request
  100	This evaluation account has exceeded its trial period. Please contact iSpeech sales at +1 (917) 338-7723 or at sales@ispeech.org to upgrade your license.
  101	Your key has been disabled. Please contact iSpeech sales at +1 (917) 338-7723 or at sales@ispeech.org to modify your license.
  1000	Invalid Request Method POST Required

---

Previous Versions

The previous version of the iSpeech API may no longer be supported. Please contact your iSpeech sales associate if you have any questions.

iSpeech API Specification Version 1.5

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)
  au   - Au 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

dictionary - The unique identifier of a user defined dictionary to use for this conversion.

• By default, no dictionary is used.

-->

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:

• fileid - The file identifier
• filesize - The file size in bytes (if available)
• format - The file format
• words - The amount of words in this conversion
• status - Either failed or finished

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

---

iSpeech API Specification Version 1.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.

---

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:

• uname - The account email address or username
• pword - The account password
• act - The requested action

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
• convert
• status
• download

---

Information

Requires:

• No required variables.

Optional:

• No optional variables.

Returns

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

• result - success on success, otherwise error, with an appropriate error code
• credits - amount of credits in account

---

Convert

Requires:

• text - The text to convert to speech

Optional:

• voice - The voice to use. Two voices are currently enabled. EngFemale1 and EngMale1 a US female and US male voice.
     Default Value: EngFemale1
• title - The title for this file (as displayed in your account window)
     Default Value: first few words of text

Returns

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

• result - success on success, otherwise error, with an appropriate error code
• hash - the file hash
• status - the file status
• words - words in text

---

Status

Requires:

• hash - The hash of the file of which to check status

Optional:

• No optional variables.

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).

• result - success on success, otherwise error, with an appropriate error code
• status - the status of the file (waiting, complete or error)
• filesize - the file size in bytes if available
• words - words in text
• eta - estimated time to completion

---

Download

Requires:

• hash - The hash of the file of which to download

Optional:

• No optional variables.

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:

• result - only error, with an appropriate error code

via ispeech.org