The TTS service provides a basic JSON HTTP web service
for the creation of audio files from text.
All service end points require the HTTP Content-Type header field to be set to
application/json. This will also be the Content-Type of all returned data as well
with the exception of audio download urls that will set an appropriate audio mime type.
The service relies on Nuance Vocalizer for all Text to speech functionality and will not operate without it.
Notice
Any audio created with this service is subject to Nuance licensing agreement and terms of use. If you do not have a current valid Vocalizer offline license you may not use the audio generated from this service either externally or internally.
The creation of audio is an asynchronous process consisting of several steps. The first step creates an audio task. After successfully creating a audio task you then monitor the task status and wait for it to complete. The final step is the retrieval of the completed audio file.
To create an audio task you will need to POST a valid JSON
request to the /audio/task resource. The request parameters are listed below. Optional parameters
will default to pre-configured values in TTS service configuration files.
If the task is valid and accepted by the service you will receive an HTTP 202 Accepted
status code. The URL where you can check on the status of the task will be in the Content-Location
HTTP header and as a link in the body of the response. If a duplicate request is made a
HTTP 409 Conflict will be returned along with the current task status.
| Parameter | Description |
|---|---|
text |
The text to be spoken. Required |
voice |
The Nuance Vocalizer voice name to use. Optional |
lang |
The language code of the Nuance Vocalizer voice. This must match language code of the
voice parameter.Optional |
format |
The format of the audio file. Can be one of 'wav', 'mp3' or 'raw'. Audio format is encoded as
µ-law,8bit, 8k for both wav and raw while mp3 is @ 128bit.
Optional. |
{"voice":"samantha","lang":"en-US","format":"mp3","text":"The text to speak."}
{"text":"The text to speak."}
{"id":"9c41efbc0c4f9245a81950070671c4a01a300fa3","state":"pending","message":"Success, task is now pending.","links":[{"rel":"self","href":"http://<host>/audio/task/9c41efbc0c4f9245a81950070671c4a01a300fa3"}]}
Once the audio task has been created its status can be checked periodically to determine when it is complete.
While the task has a status of pending, you will receive a HTTP 200 OK
status code along with the current task status. If the task completes successfully you will receive a
HTTP 303 See Other status code. The URL where you can download the completed audio
will be in the Content-Location HTTP header.
| Field | Description |
|---|---|
id |
The task id this status is for. |
status |
The current status of the task that will be one of pending, done,
failed or unknown.
|
message |
A more detailed message explaining the status value.
|
{"id":"9c41efbc0c4f9245a81950070671c4a01a300fa3","state":"pending","message":"Success, task is now pending.","links":[{"rel":"self","href":"http://<host>/audio/task/9c41efbc0c4f9245a81950070671c4a01a300fa3"}]}
{"id":"9c41efbc0c4f9245a81950070671c4a01a300fa3","state":"done","message":"Audio generation is now complete","links":[{"rel":"self","href":"http://<host>/audio/task/9c41efbc0c4f9245a81950070671c4a01a300fa3"},{"rel":"audio","href":"http://<host>/audio/9c41efbc0c4f9245a81950070671c4a01a300fa3"}]}>
When an audio task has completed you will receive a URL in the Content-Location header. A simple
HTTP GET request will allow you to download the audio.
http://<host>/audio/9c41efbc0c4f9245a81950070671c4a01a300fa3