Curl Node Java

Text to Speech

API Reference
IBM Text to Speech API reference

Introduction

The IBM® Text to Speech service provides an API that uses IBM's speech-synthesis capabilities to synthesize text into natural-sounding speech in a variety of languages, accents, and voices. The service supports at least one male or female voice, sometimes both, for each language. The audio is streamed back to the client with minimal delay.

The Text to Speech API consists of the following groups of related calls:

  • Voices includes methods that provide information about the voices available for synthesized speech.

  • Synthesis includes methods that synthesize written text to spoken audio over the HTTP protocol. The calls support plain text and SSML input.

  • WebSockets includes a method that synthesizes text to audio over the WebSocket protocol. The call supports plain text and SSML input, including the <mark> element as well as word timing information for all strings of the input text.

  • Pronunciation includes a single method that returns the pronunciation for a specified word.

  • Custom models provides methods for creating custom voice models. Custom models let users create a dictionary of words and their translations for use in speech synthesis.

  • Custom words provides methods that let users manage the word/translation pairs in a custom voice model.

Usage guidelines

The following usage information pertains to many of the calls:

  • Many calls refer to the Speech Synthesis Markup Language (SSML), an XML-based markup language that provides annotations of text for speech-synthesis applications; for example, many methods accept or produce translations that use an SSML-based phoneme format. For more information about support for SSML, see Using SSML and Using SPRs.

  • The pronunciation and customization calls accept or return a Globally Unique Identifier (GUID); for example, customization IDs and service credentials are GUIDs. GUIDs are hexadecimal strings that have the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

  • Many customization calls accept or return sounds-like or phonetic translations for words. A phonetic translation is based on the SSML format for representing the phonetic string of a word. Phonetic translations can occur in one of two formats: the standard International Phonetic Alphabet (IPA) representation, for example

        <phoneme alphabet=\"ipa\" ph=\"təmˈɑto\"></phoneme>

    or the proprietary IBM Symbolic Phonetic Representation (SPR), for example

        <phoneme alphabet=\"ibm\" ph=\"1gAstroEntxrYFXs\"></phoneme>

    For more information about customization and about sounds-like and phonetic translations, see Understanding customization and Using customization.

  • In all cases, you must use service credentials created for the instance of the service that owns a custom voice model to use the methods described in this documentation with that model. For more information, see Ownership of custom voice models.

HTTP API Endpoint


https://stream.watsonplatform.net/text-to-speech/api

WebSocket API endpoint


wss://stream.watsonplatform.net/text-to-speech/api

The code examples on this tab use the client library that is provided for Node.js.

GitHub

https://github.com/watson-developer-cloud/node-sdk

Node Package Manager


npm install watson-developer-cloud

The code examples on this tab use the client-side library that is provided for Java.

GitHub

https://github.com/watson-developer-cloud/java-sdk

Maven


<dependency>
  <groupId>com.ibm.watson.developer_cloud</groupId>
  <artifactId>java-sdk</artifactId>
  <version>3.9.1</version>
</dependency>

Gradle


compile 'com.ibm.watson.developer_cloud:java-wrapper:3.9.1'

Synchronous and asynchronous requests

The Java SDK supports both synchronous (blocking) and asynchronous (non-blocking) execution of all methods. All methods are called with the Java ServiceCall interface.

  • To call a method synchronously, use the execute method of the ServiceCall interface. You can also call the execute method directly from an instance of the service, as shown in Get voices. Note that the method can return an unchecked RuntimeException.

  • To call a method asynchronously, use the enqueue method of the ServiceCall interface to receive a callback when the response arrives. The ServiceCallback interface of the method's argument provides onResponse and onFailure methods that you override to handle the callback.

Example synchronous request


ServiceCall call = service.getVoices();
List<Voice> voices = call.execute();

Example asynchronous request


ServiceCall call = service.getVoices();
call.enqueue(new ServiceCallback<List<Voice>>() {
  @Override public void onResponse(List<Voice> voices) {
    . . .
  }
  @Override public void onFailure(Exception e) {
    . . .
  }
});

More information

An interactive tool for testing calls to the API and viewing live responses from the service is available in the Text to Speech API explorer. Descriptions of Node classes referred to in this reference are available in the Node documentation for the Watson Developer Cloud Node.js SDK. Descriptions of Java classes referred to in this reference are available in the Javadoc for the Watson Developer Cloud Java SDK. Detailed information about using the service is available at About Text to Speech.

Authentication

You authenticate to the Text to Speech API by providing the username and password that are provided in the service credentials for the service instance that you want to use. The API uses HTTP basic authentication.

After creating an instance of the Text to Speech service, select Service Credentials from the navigation on the left side of its dashboard page to see the username and password that are associated with the instance. For more information, see Service credentials for Watson services.

Applications can also use tokens to establish authenticated communications with Watson services without embedding their service credentials in every call. You write an authentication proxy in Bluemix to obtain a token for your client application, which can then use the token to call the service directly. You use your service credentials to obtain a token for that service. For more information, see Tokens for authentication.

Replace {username} and {password} with your service credentials. Use either of the two constructors shown.


curl -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/{method}"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});


TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

TextToSpeech service = new TextToSpeech("{username}", "{password}");

Request logging

By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out request header to true for all requests. (Any value other than false or 0 disables request logging for that call.) You must set the header on each request that you do not want IBM to access for general service improvements. set the X-Watson-Learning-Opt-Out request header to true when you create the instance. (Any value other than false or 0 disables request logging for that instance.) You must set the header when you create the instance whose calls you do not want IBM to access for general service improvements.

Request logging for the customization interface

The service does not log data (words and translations) that are used to build custom language models; your training data is never used to improve the service's base models. The service does log data when a custom model is used with a synthesize request; you must set the X-Watson-Learning-Opt-Out request header to prevent logging for synthesize requests. For more information, see Request logging and data privacy.


curl -u "{username}":"{password}"
--header "X-Watson-Learning-Opt-Out: true"
"https://stream.watsonplatform.net/text-to-speech/api/v1/{method}"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1({
  username: '{username}',
  password: '{password}',
  headers: {
    'X-Watson-Learning-Opt-Out': 'true'
  }
});

Map<String, String> headers = new HashMap<String, String>();
headers.put("X-Watson-Learning-Opt-Out", "true");

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");
service.setDefaultHeaders(headers);

Response handling

The Text to Speech service uses standard HTTP response codes to indicate whether a method completed successfully. A 200-level response always indicates success. A 300-level response indicates the requested resource has not been modified. A 400-level response indicates some sort of input failure. And a 500-level response typically indicates an internal system error. Response codes are listed with the individual calls.

Response codes that indicate success are not readily available with the Node.js SDK. In general, the lack of an error response indicates a 200-level success response. For errors, response codes are indicated in the error object that is returned.

The Java SDK raises equivalent exceptions, which are listed with the individual methods. The exceptions include the error message returned by the service. All methods that accept an argument can throw the following exception.

Exception Description
IllegalArgumentException An illegal argument was passed to the method.

Error format

Name Description
error string Description of the error.
code integer HTTP status code.
code_description string Response message that describes the problem.
Name Description
Exception string The name of the exception that was raised.
status integer The HTTP status code.
error string A description of the error.

Example error


{
  "error": "Model en-US_Allison not found",
  "code": 404,
  "code_description": "No Such Resource"
}

{
  Error: Model en-US_Voice not found
  . . .
  code: 404,
  error: 'Model en-US_Voice not found',
  code_description: 'No Such Resource'
}

SEVERE: GET https://stream.watsonplatform.net/text-to-speech/api/v1/voices/en-US_Allison, status: 404, error: Model en-US_Allison not found
Exception in thread "main" com.ibm.watson.developer_cloud.service.exception.NotFoundException: Model en-US_Allison not found
   . . .

Voices

Get voices

Retrieves a list of all voices available for use with the service. The information includes the name, language, gender, and other details about the voice. The method returns a list of Java Voice objects; you can pass any of the objects as a parameter of the Synthesize audio method. To see information about a specific voice, use the Get a voice method.


GET /v1/voices

voices(params, callback())

ServiceCall<List<Voice>> getVoices()

Request

No arguments.

Example request


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/voices"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

text_to_speech.voices(null, function(error, voices) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(voices, null, 2));

});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

List<Voice> voices = service.getVoices().execute();
System.out.println(voices);

Response

VoiceSet
Name Description
voices object[ ] An array of Voice objects that provides information about all available voices.

Returns a List of Java Voice objects. Each object provides the same information as a JSON Voice object.

Voice (Java Voice object)
Name Description
url string The URI of the voice.
gender string The gender of the voice: male or female.
name string The name of the voice. Use this value as the voice identifier in all requests that accept a voice.
language string The language and region of the voice; for example, en-US for US English.
description string A description of the voice.
supported_features object A SupportedFeatures object that describes the additional service features supported with the voice.
customizable boolean Indicates whether the voice can be customized with a custom voice model. (Same as the custom_pronunciation field of the SupportedFeatures object; maintained for backward compatibility.)
SupportedFeatures (Java Voice.SupportedFeatures object)
Name Description
custom_pronunciation boolean Indicates whether the voice can be customized with a custom voice model. (Same as customizable.)
voice_transformation boolean Indicates whether the voice can be transformed by using the SSML voice-transformation element.

Response codes

Status Description
200 OK The request succeeded.
304 Not Modified The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification.
406 Not Acceptable The request specified an Accept header with an incompatible content type.
415 Unsupported Media Type The request specified an unacceptable media type.

Exceptions thrown

Exception Description
ServiceResponseException The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (HTTP response code 304.)
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)
ForbiddenException The request specified an incompatible content type. (HTTP response code 406.)
UnsupportedException The request specified an unacceptable media type. (HTTP response code 415.)

Example response


{
  "voices": [
    {
      "name": "pt-BR_IsabelaVoice",
      "language": "pt-BR",
      "customizable": true,
      "gender": "female",
      "url": "https://stream-s.watsonplatform.net/text-to-speech/api/v1/voices/pt-BR_IsabelaVoice",
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Isabela: Brazilian Portuguese (português brasileiro) female voice."
    },
    {
      "name": "es-US_SofiaVoice",
      "language": "es-US",
      "customizable": true,
      "gender": "female",
      "url": "https://stream-s.watsonplatform.net/text-to-speech/api/v1/voices/es-US_SofiaVoice",
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Sofia: North American Spanish (español norteamericano) female voice."
    },
    {
      "name": "en-GB_KateVoice",
      "language": "en-GB",
      "customizable": true,
      "gender": "female",
      "url": "https://stream-s.watsonplatform.net/text-to-speech/api/v1/voices/en-GB_KateVoice",
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Kate: British English female voice."
    },
    {
      "name": "en-US_LisaVoice",
      "language": "en-US",
      "customizable": true,
      "gender": "female",
      "url": "https://stream-s.watsonplatform.net/text-to-speech/api/v1/voices/en-US_LisaVoice",
      "supported_features": {
        "voice_transformation": true,
        "custom_pronunciation": true
      },
      "description": "Lisa: American English female voice."
    },
    {
      "name": "ja-JP_EmiVoice",
      "language": "ja-JP",
      "customizable": true,
      "gender": "female",
      "url": "https://stream-s.watsonplatform.net/text-to-speech/api/v1/voices/ja-JP_EmiVoice",
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Emi: Japanese (日本語) female voice."
    },
    . . .
  ]
}

[
  {
    "description": "Sofia: Latin American Spanish (español latinoamericano) female voice.",
    "gender": "female",
    "language": "es-LA",
    "name": "es-LA_SofiaVoice",
    "supported_features": {
      "custom_pronunciation": true,
      "voice_transformation": false
    },
    "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/es-LA_SofiaVoice"
  },
  {
    "description": "Isabela: Brazilian Portuguese (português brasileiro) female voice.",
    "gender": "female",
    "language": "pt-BR",
    "name": "pt-BR_IsabelaVoice",
    "supported_features": {
      "custom_pronunciation": true,
      "voice_transformation": false
    },
    "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/pt-BR_IsabelaVoice"
  },
  {
    "description": "Michael: American English male voice.",
    "gender": "male",
    "language": "en-US",
    "name": "en-US_MichaelVoice",
    "supported_features": {
      "custom_pronunciation": true,
      "voice_transformation": true
    },
    "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/en-US_MichaelVoice"
  },
  {
    "description": "Emi: Japanese (日本語) female voice.",
    "gender": "female",
    "language": "ja-JP",
    "name": "ja-JP_EmiVoice",
    "supported_features": {
      "custom_pronunciation": true,
      "voice_transformation": false
    },
    "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/ja-JP_EmiVoice"
  },
  {
    "description": "Allison: American English female voice.",
    "gender": "female",
    "language": "en-US",
    "name": "en-US_AllisonVoice",
    "supported_features": {
      "custom_pronunciation": true,
      "voice_transformation": true
    },
    "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/en-US_AllisonVoice"
  },
  . . .
]

Get a voice

Lists information about the specified voice. The information includes the name, language, gender, and other details about the voice. Specify a customization ID to obtain information for that custom voice model of the specified voice. The method returns a Java Voice object that you can pass as a parameter of the Synthesize audio method. To see information about all available voices, use the Get voices method.


GET /v1/voices/{voice}

voice(params, callback())

ServiceCall<Voice> getVoice(String voiceName)
ServiceCall<Voice> getVoice(String voiceName, String customizationId)

Request

Parameter Type Description
voice path string The voice about which information is to be returned:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice
  • es-ES_LauraVoice
  • es-ES_EnriqueVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
customization_id query string The GUID of a custom voice model about which information is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to see information about the voice with no customization.
Parameter Description
voice voiceName string The voice about which information is to be returned:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice
  • es-ES_LauraVoice
  • es-ES_EnriqueVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
customization_id customizationId string The GUID of a custom voice model about which information is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to see information about the voice with no customization.

Example request


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/voices/en-us_AllisonVoice"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var fs = require('fs');

var text_to_speech = new TextToSpeechV1({
  username: '{username}',
  password: '{password}'
});

var params = {
  voice: 'en-US_AllisonVoice'
};

text_to_speech.voice(params, function(error, voice) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(voice, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

Voice voice = service.getVoice("en-US_AllisonVoice").execute();
System.out.println(voice);

Response

Returns a single Java Voice object for the specified voice. The information is the same as that described for the JSON VoiceCustomization object.

VoiceCustomization (Java Voice object)
Name Description
url string The URI of the voice.
gender string The gender of the voice: male or female.
name string The name of the voice. Use this value as the voice identifier in all requests that accept a voice.
language string The language and region of the voice; for example, en-US for US English.
description string A description of the voice.
supported_features object A SupportedFeatures object that describes the additional service features supported with the voice.
customization object A Customization object that provides information about a specific custom voice model for the voice. Returned only when a customization_id customizationId is specified with the call.
customizable boolean Indicates whether the voice can be customized with a custom voice model. (Same as custom_pronunciation; maintained for backward compatibility.)

Response codes

Status Description
200 OK The request succeeded.
304 Not Modified The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'customization_id'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
406 Not Acceptable The request specified an Accept header with an incompatible content type.
415 Unsupported Media Type The request specified an unacceptable media type.

Exceptions thrown

Exception Description
ServiceResponseException The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (HTTP response code 304.)
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)
ForbiddenException The request specified an incompatible content type. (HTTP response code 406.)
UnsupportedException The request specified an unacceptable media type. (HTTP response code 415.)

Example response


{
  "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/en-US_AllisonVoice",
  "name": "en-US_AllisonVoice",
  "language": "en-US",
  "customizable": true,
  "gender": "female",
  "description": "Allison: American English female voice.",
  "supported_features": {
    "custom_pronunciation": true,
    "voice_transformation": true
  }
}

{
  "description": "Allison: American English female voice.",
  "gender": "female",
  "language": "en-US",
  "name": "en-US_AllisonVoice",
  "supported_features": {
    "custom_pronunciation": true,
    "voice_transformation": true
  },
  "url": "https://stream.watsonplatform.net/text-to-speech/api/v1/voices/en-US_AllisonVoice"
}

Synthesis

Synthesize audio

Synthesizes text to spoken audio, returning the synthesized audio stream as an array of bytes. You can use two request methods to synthesize audio:

  • The HTTP GET request method passes shorter text via a query parameter. The text size is limited by the maximum length of the HTTP request line and headers (about 6 KB) or by system limits, whichever is less.

  • The HTTP POST request method passes longer text in the body of the request. Text size is limited to 5 KB.

With either request method, you can provide plain text or text that is annotated with SSML.

Synthesizes text to spoken audio, returning the synthesized audio stream as an array of bytes. You can provide plain text or text that is annotated with SSML. You can use a callback method to handle the results asynchronously, or you can pipe the binary stream to a file by using the Node fs module, as shown in the example request.


GET /v1/synthesize
POST /v1/synthesize

synthesize(options, callback())

ServiceCall<InputStream> synthesize(String text, Voice voice)
ServiceCall<InputStream> synthesize(String text, Voice voice,
  AudioFormat audioFormat)
ServiceCall<InputStream> synthesize(String text, Voice voice,
  AudioFormat audioFormat, String customizationId)

Request

Parameter Type Description
text query string For an HTTP GET request, the text to be synthesized. Provide plain text or text that is annotated with SSML. Text size is limited by the maximum length of the HTTP request line and headers (about 6 KB) or by system limits, whichever is less. Not supported for POST requests.
body body object For an HTTP POST request, a Text object that provides the text to be synthesized. Provide plain text or text that is annotated with SSML. Text size is limited to 5 KB. Not supported for GET requests.
Content-Type query string For an HTTP POST request, specify application/json to indicate the type of the input. Omit for GET requests.
Accept header string The requested MIME type of the audio:
  • audio/ogg (the service uses the Vorbis codec)
  • audio/ogg;codecs=opus (the default)
  • audio/ogg;codecs=vorbis
  • audio/wav
  • audio/flac
  • audio/mp3
  • audio/mpeg
  • audio/webm (the service uses the Opus codec)
  • audio/webm;codecs=opus
  • audio/webm;codecs=vorbis
  • audio/l16;rate=rate
  • audio/mulaw;rate=rate
  • audio/basic
You can use this header or the accept query parameter to specify the MIME type. For additional information about the supported audio formats and sampling rates, see Specifying an audio format. The information includes links to a number of Internet sites that provide technical and usage details about the different formats.
accept query string The requested MIME type of the audio:
  • audio/ogg (the service uses the Vorbis codec)
  • audio/ogg;codecs=opus (the default)
  • audio/ogg;codecs=vorbis
  • audio/wav
  • audio/flac
  • audio/mp3
  • audio/mpeg
  • audio/webm (the service uses the Opus codec)
  • audio/webm;codecs=opus
  • audio/webm;codecs=vorbis
  • audio/l16;rate=rate
  • audio/mulaw;rate=rate
  • audio/basic
You can use this query parameter or the Accept header to specify the MIME type. For additional information about the supported audio formats and sampling rates, see Specifying an audio format. The information includes links to a number of Internet sites that provide technical and usage details about the different formats.
voice query string The voice that is to be used for the synthesis:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice (the default)
  • es-ES_EnriqueVoice
  • es-ES_LauraVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
customization_id query string The GUID of a custom voice model that is to be used for the synthesis. If you specify a custom voice model, it is guaranteed to work only if it matches the language of the indicated voice. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customization.
Text
Name Description
text string The text to be synthesized.
Parameter Description
text string The text to be synthesized. Provide plain text or text that is annotated with SSML. Text size is limited to 5 KB.
accept string The requested MIME type of the audio:
  • audio/ogg (the service uses the Vorbis codec)
  • audio/ogg;codecs=opus (the default)
  • audio/ogg;codecs=vorbis
  • audio/wav
  • audio/flac
  • audio/mp3
  • audio/mpeg
  • audio/webm (the service uses the Opus codec)
  • audio/webm;codecs=opus
  • audio/webm;codecs=vorbis
  • audio/l16;rate=rate
  • audio/mulaw;rate=rate
  • audio/basic
For additional information about the supported audio formats and sampling rates, see Specifying an audio format. The information includes links to a number of Internet sites that provide technical and usage details about the different formats.
voice string The voice that is to be used for the synthesis:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice (the default)
  • es-ES_EnriqueVoice
  • es-ES_LauraVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
customization_id string The GUID of a custom voice model that is to be used for the synthesis. If you specify a custom voice model, it is guaranteed to work only if it matches the language of the indicated voice. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customization.
X-Watson-Learning-Opt-Out boolean Indicates whether Bluemix is to collect data from the request. The default is false; data is collected for the request and response. For more information, see Request logging.
Parameter Description
text string The text to be synthesized. Provide plain text or text that is annotated with SSML. Text size is limited to 5 KB.
voice object The Java Voice object for the voice that is to be used for the synthesis:
  • Voice.DE_BIRGIT (de-DE_BirgitVoice)
  • Voice.DE_DIETER (de-DE_DieterVoice)
  • Voice.EN_ALLISON (en-US_AllisonVoice)
  • Voice.EN_LISA (en-US_LisaVoice)
  • Voice.EN_MICHAEL (en-US_MichaelVoice)
  • Voice.ES_ENRIQUE (es-ES_EnriqueVoice)
  • Voice.ES_LAURA (es-ES_LauraVoice)
  • Voice.ES_SOFIA (es-US_SofiaVoice)
  • Voice.FR_RENEE (fr-FR_ReneeVoice)
  • Voice.GB_KATE (en-GB_KateVoice)
  • Voice.IT_FRANCESCA (it-IT_FrancescaVoice)
  • Voice.JA_EMI (ja-JP_EmiVoice)
  • Voice.LA_SOFIA (es-LA_SofiaVoice)
  • Voice.PT_ISABELA (pt-BR_IsabelaVoice)
audioFormat object The Java AudioFormat object for the requested MIME type of the audio:
  • AudioFormat.BASIC (audio/basic)
  • AudioFormat.FLAC (audio/flac)
  • AudioFormat.OGG (audio/ogg;codecs=opus)
  • AudioFormat.OGG_VORBIS (audio/ogg;codecs=vorbis)
  • AudioFormat.PCM (deprecated)
  • AudioFormat.WAV (audio/wav, the default)
  • AudioFormat.WEBM (audio/webm)
  • AudioFormat.WEBM_OPUS (audio/webm;codecs=opus)
  • AudioFormat.WEBM_VORBIS (audio/webm;codecs=vorbis)
For additional information about the supported audio formats and sampling rates, see Specifying an audio format. The information includes links to a number of Internet sites that provide technical and usage details about the different formats.
customizationId string The GUID of a custom voice model that is to be used for the synthesis. If you specify a custom voice model, it is guaranteed to work only if it matches the language of the indicated voice. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customization.

Example GET request


curl -X GET -u "{username}":"{password}"
--output hello_world.wav
"https://stream.watsonplatform.net/text-to-speech/api/v1/synthesize?accept=audio/wav&text=Hello%20world&voice=en-US_AllisonVoice"

Example POST request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--header "Accept: audio/wav"
--data "{\"text\":\"Hello world\"}"
--output hello_world.wav
"https://stream.watsonplatform.net/text-to-speech/api/v1/synthesize?voice=en-US_AllisonVoice"

Example request


var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var fs = require('fs');

var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  text: 'Hello world',
  voice: 'en-US_AllisonVoice',
  accept: 'audio/wav'
};

// Pipe the synthesized text to a file.
text_to_speech.synthesize(params).on('error', function(error) {
  console.log('Error:', error);
}).pipe(fs.createWriteStream('hello_world.wav'));

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

try {
  String text = "Hello world";
  InputStream stream = service.synthesize(text, Voice.EN_ALLISON,
    AudioFormat.WAV).execute();
  InputStream in = WaveUtils.reWriteWaveHeader(stream);
  OutputStream out = new FileOutputStream("hello_world.wav");
  byte[] buffer = new byte[1024];
  int length;
  while ((length = in.read(buffer)) > 0) {
    out.write(buffer, 0, length);
  }
  out.close();
  in.close();
  stream.close();
}
catch (Exception e) {
  e.printStackTrace();
}

Response

Returns the audio stream for the specified text as an array of bytes in the specified MIME type.

Response headers

Name Description
Warnings string Warning messages about invalid query parameters or JSON fields included with the request. The warning includes a descriptive message and a list of invalid argument strings. For example, a message such as \"Unknown arguments:\" or \"Unknown url query arguments:\" followed by a list of the form \"invalid_arg_1, invalid_arg_2.\" The request succeeds despite the warnings.

Response codes

Status Description
200 OK The request succeeded.
304 Not Modified The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure.
406 Not Acceptable The request specified an incompatible content type or failed to specify a required sampling rate.
415 Unsupported Media Type The request specified an unacceptable media type.
500 Internal Server Error The service experienced an internal error.
503 Service Unavailable The service is currently unavailable.

Exceptions thrown

Exception Description
ServiceResponseException The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (HTTP response code 304.)
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)
ForbiddenException The request specified an incompatible content type or failed to specify a required sampling rate. (HTTP response code 406.)
UnsupportedException The request specified an unacceptable media type. (HTTP response code 415.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)
ServiceUnavailableException The service is currently unavailable. (HTTP response code 503.)

Example response

An output file named hello_world.wav.

WebSockets

Synthesize audio

Synthesizes text to spoken audio over a WebSocket connection. The synthesize method establishes a connection with the service. You then send the text to be synthesized to the service as a JSON text message over the connection, and the service returns the audio as a binary stream of data.

You can provide a maximum of 5 KB of either plain text or text that is annotated with SSML. You can use the SSML <mark> element to request the location of the marker in the audio stream. You can also request word timing information in the form of start and end times for all strings of the input text. Mark and word timing results are sent as text messages over the connection.

Not supported.


/v1/synthesize

Request

The client establishes a connection with the service by using the WebSocket constructor to create an instance of a WebSocket connection object. The constructor sets the following basic parameters for the connection and the synthesis.

Parameter Type Description
watson-token query string Provides an authentication token for the service. The token is used instead of service credentials. You must pass a valid token via either this parameter or the X-Watson-Authorization-Token header. For more information, see Authentication.
X-Watson-Authorization-Token header string Provides an authentication token for the service. The token is used instead of service credentials. You must pass a valid token via either this header or the watson-token query parameter. For more information, see Authentication.
voice query string The voice that is to be used for the synthesis:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice (the default)
  • es-ES_LauraVoice
  • es-ES_EnriqueVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
customization_id query string The GUID of a custom voice model that is to be used for the synthesis. If you specify a custom voice model, it is guaranteed to work only if it matches the language of the indicated voice. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customization.
x-watson-learning-opt-out query boolean Indicates whether to opt out of data collection for the request sent over the connection. The default is false; data is collected for the request and response. You can also opt out of request logging by passing a value of true with the X-Watson-Learning-Opt-Out request header; see Request logging.

The client initiates the synthesis by sending a JSON-formatted text message to the service over the connection.

Parameter Type Description
text string The text to be synthesized. Provide plain text or text that is annotated with SSML. SSML input can include the SSML <mark> element. Text size is limited to 5 KB.
accept string The requested MIME type of the audio:
  • audio/ogg (the service uses the Vorbis codec)
  • audio/ogg;codecs=opus (the default)
  • audio/ogg;codecs=vorbis
  • audio/wav
  • audio/flac
  • audio/mp3
  • audio/mpeg
  • audio/webm (the service uses the Opus codec)
  • audio/webm;codecs=opus
  • audio/webm;codecs=vorbis
  • audio/l16;rate=rate
  • audio/mulaw;rate=rate
  • audio/basic
  • */* (specifies the default audio format, audio/ogg;codecs=opus)
For additional information about the supported audio formats and sampling rates, see Specifying an audio format. The information includes links to a number of Internet sites that provide technical and usage details about the different formats.
timings string[ ] A list that specifies whether the service is to return word timing information for all strings of the input text. Specify words to request word timing information; the start and end time of each word of the input is returned. Specify an empty list or omit the parameter to receive no word timing information. Not supported for Japanese input text.

Example request

var voice = "en-US_AllisonVoice";
var format = 'audio/ogg;codecs=opus';
var token = "{authentication-token}";
var wsURI = "wss://stream.watsonplatform.net/text-to-speech/api/v1/synthesize?voice=" +
  voice + "&watson-token=" + token;

function onOpen(evt) {
  var message = {
    text: "Hello world",
    accept: format
  };
  // The service currently accepts a single message per WebSocket connection.
  websocket.send(JSON.stringify(message));
}

var audioParts = [];
var finalAudio;

function onMessage(evt) {
  if (typeof evt.data === 'string') {
    console.log('Received string message: ', evt.data)
  } else {
    console.log('Received ' + evt.data.size + ' binary bytes', evt.data.type);
    audioParts.push(evt.data);
  }
}

function onClose(evt) {
  console.log('WebSocket closed', evt.code, evt.reason);
  finalAudio = new Blob(audioParts, {type: format});
  console.log('final audio: ', finalAudio);
}

function onError(evt) {
  console.log('WebSocket error', evt);
}

var websocket = new WebSocket(wsURI);
websocket.onopen = onOpen;
websocket.onclose = onClose;
websocket.onmessage = onMessage;
websocket.onerror = onError;

Response

Returns the audio stream for the input text as an array of bytes in the specified MIME type. If the input text includes one or more SSML <mark> tags, the service returns one or more text messages that include one or more Marks objects.

Marks
Name Description
marks string[ ] The location of one or more marks in the audio stream. Each inner list consists of two elements: the name of the mark and the time in seconds at which it occurs in the audio. For example, [["here", 0.4019387755102041]].

If the request includes the timings parameter to request word timing information, the service returns one or more text messages that include one or more Timings objects.

Timings
Name Description
timings string[ ] Word timing information for one or more strings in the audio stream. Each inner list consists of three elements: a word from the input text followed by the start and end time in seconds at which it occurs in the audio. For example, ["Hello", [0.0690258394023930, 0.1655782733012873]].

Response handling

The WebSocket constructor returns an instance of a WebSocket connection object. You assign application-specific calls to the following methods of the object to handle events associated with the connection. Each event handler must accept a single argument for the event from the connection that causes it to execute.

Event Description
onopen Status of the connection's opening.
onmessage Response messages for the connection, including the results of the synthesis as a binary stream.
onerror Errors for the connection or request.
onclose Status of the connection's closing.

The connection can produce the following return codes.

Return code Description
1000 The connection closed normally.
1002 The service is closing the connection due to a protocol error.
1006 The connection was closed abnormally.
1009 The frame size exceeded the 4 MB limit.
1011 The service is terminating the connection because it encountered an unexpected condition that prevents it from fulfilling the request, such as an invalid argument. The return code can also indicate that the input text was too large; the text cannot exceed 5 KB in size.

If any errors or warnings are associated with the connection, the service sends a JSON response with one of the following fields.

Name Description
error string A response message that describes the problem. The connection is closed. The message is followed by a message that includes the boolean value true to indicate that the connection is closed, the return code for the error, and a brief message.
warnings string[ ] Warning messages about invalid or unknown parameters included with the request. The warning includes a descriptive message and a list of invalid argument strings. For example, a message such as \"Unknown arguments: invalid_arg_1, invalid_arg_2.\" The connection remains open.

Pronunciation

Get pronunciation

Returns the phonetic pronunciation for the specified word. You can request the pronunciation for a specific format. You can also request the pronunciation for a specific voice to see the default translation for the language of that voice or for a specific custom voice model to see the translation for that voice model.


GET /v1/pronunciation

pronunciation(params, callback())

ServiceCall<Pronunciation> getPronunciation(String word, Voice voice,
  Phoneme phoneme)
ServiceCall<Pronunciation> getPronunciation(String word, Voice voice,
  Phoneme phoneme, String customizationID)

Request

Parameter Type Description
text query string The word for which the pronunciation is requested.
voice query string The voice in which the pronunciation for the specified word is to be returned:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • es-ES_EnriqueVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice (the default)
  • es-ES_LauraVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
The translation is returned in the language of the specified voice; all voices for the same language (for example, en-US) return the same translation. Do not specify both a voice and a customization_id.
format query string The phoneme set in which the pronunciation is to be returned:
  • ipa (the default)
  • ibm
customization_id query string The GUID of a custom voice model for which the pronunciation is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model. If the word is not defined in the specified voice model, the service returns the default translation for the model's language. Omit the parameter to see the translation for the specified voice with no customization. Do not specify both a voice and a customization_id.
Parameter Description
text string The word for which the pronunciation is requested.
voice string The voice in which the pronunciation for the specified word is to be returned:
  • de-DE_BirgitVoice
  • de-DE_DieterVoice
  • en-GB_KateVoice
  • es-ES_EnriqueVoice
  • en-US_AllisonVoice
  • en-US_LisaVoice
  • en-US_MichaelVoice (the default)
  • es-ES_LauraVoice
  • es-LA_SofiaVoice
  • es-US_SofiaVoice
  • fr-FR_ReneeVoice
  • it-IT_FrancescaVoice
  • ja-JP_EmiVoice
  • pt-BR_IsabelaVoice
The translation is returned in the language of the specified voice; all voices for the same language (for example, en-US) return the same translation. Do not specify both a voice and a customization_id.
format string The phoneme set in which the pronunciation is to be returned:
  • ipa (the default)
  • ibm
customization_id string The GUID of a custom voice model for which the pronunciation is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model. If the word is not defined in the specified voice model, the service returns the default translation for the model's language. Omit the parameter to see the translation for the specified voice with no customization. Do not specify both a voice and a customization_id.
Parameter Description
text string The word for which the pronunciation is requested.
voice object The Java Voice object for the voice in which the pronunciation for the specified word is to be returned:
  • Voice.DE_BIRGIT (de-DE_BirgitVoice)
  • Voice.DE_DIETER (de-DE_DieterVoice)
  • Voice.EN_ALLISON (en-US_AllisonVoice)
  • Voice.EN_LISA (en-US_LisaVoice)
  • Voice.EN_MICHAEL (en-US_MichaelVoice, the default)
  • Voice.ES_ENRIQUE (es-ES_EnriqueVoice)
  • Voice.ES_LAURA (es-ES_LauraVoice)
  • Voice.ES_SOFIA (es-US_SofiaVoice)
  • Voice.FR_RENEE (fr-FR_ReneeVoice)
  • Voice.GB_KATE (en-GB_KateVoice)
  • Voice.IT_FRANCESCA (it-IT_FrancescaVoice)
  • Voice.JA_EMI (ja-JP_EmiVoice)
  • Voice.LA_SOFIA (es-LA_SofiaVoice)
  • Voice.PT_ISABELA (pt-BR_IsabelaVoice)
The translation is returned in the language of the specified voice; all voices for the same language (for example, en-US) return the same translation. Do not specify both a voice and a customizationId.
phoneme object The Java Phoneme object for the phoneme set in which the pronunciation is to be returned:
  • Phoneme.IPA (ipa, the default)
  • Phoneme.SPR (ibm)
customizationId string The GUID of a custom voice model for which the pronunciation is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model. If the word is not defined in the specified voice model, the service returns the default translation for the model's language. Omit the parameter to see the translation for the specified voice with no customization. Do not specify both a voice and a customizationId.

Example request for IPA format


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/pronunciation?text=IEEE"

Example request for IBM format


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/pronunciation?text=IEEE&format=ibm"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var fs = require('fs');

var text_to_speech = new TextToSpeechV1({
  username: '{username}',
  password: '{password}'
});

var params = {
  text: 'IEEE',
  format: 'ibm'
};

text_to_speech.pronunciation(params, function(error, pronunciation) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(pronunciation, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

Pronunciation pronunciation = service.getPronunciation("IEEE", Voice.EN_ALLISON,
  Phoneme.SPR).execute();
System.out.println(pronunciation);

Response

Pronunciation (Java Pronunciation object)
Name Description
pronunciation string The pronunciation of the specified text in the requested voice and format and, if specified, for the requested custom voice model.

Response codes

Status Description
200 OK The request succeeded.
304 Not Modified The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid parameter 'name' in request
  • Required parameter 'name' is missing
  • Invalid header value for 'header'
  • Invalid value for 'customization_id'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
404 Not Found The specified voice model was not found:
  • Model model not found.
406 Not Acceptable The request specified an Accept header with an incompatible content type.
500 Internal Server Error The service experienced an internal error.
503 Service Unavailable The service is currently unavailable.

Exceptions thrown

Exception Description
ServiceResponseException The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (HTTP response code 304.)
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)
NotFoundException The request voice model was not found. (HTTP response code 404.)
ForbiddenException The request specified an incompatible content type. (HTTP response code 406.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)
ServiceUnavailableException The service is currently unavailable. (HTTP response code 503.)

Example response for IPA format


{
  "pronunciation": ".ˈaɪ .ˈi .ˈi .ˈi"
}

Example response for IBM format


{
  "pronunciation": "`[.1Y] `[.1i] `[.1i] `[.1i]"
}

Custom models

Create a custom model

Creates a new empty custom voice model. You must specify a name for the new custom model; you can optionally specify the language and a description of the new model. The model is owned by the instance of the service whose credentials are used to create it.


POST /v1/customizations

createCustomization(params, callback())

ServiceCall<CustomVoiceModel> createCustomVoiceModel(String name, String language,
  String description)
ServiceCall<CustomVoiceModel> saveCustomVoiceModel(CustomVoiceModel model) DEPRECATED

Request

Parameter Type Description
Content-Type query string The type of the input, application/json.
body body object A CustomVoice object that provides information about the new custom voice model.
CustomVoice
Name Description
name string The name of the new custom voice model.
language string The language of the new custom voice model:
  • de-DE
  • en-GB
  • en-US (the default)
  • es-ES
  • es-LA
  • es-US
  • fr-FR
  • it-IT
  • ja-JP
  • pt-BR
description string A description of the new custom voice model.
Name Description
name string The name of the new custom voice model.
language string The language of the new custom voice model:
  • de-DE
  • en-GB
  • en-US (the default)
  • es-ES
  • es-LA
  • es-US
  • fr-FR
  • it-IT
  • ja-JP
  • pt-BR
Specify null to create the new custom model with the default language.
description string A description of the new custom voice model. Specify null to create the new custom model with no description.

Example request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--data "{\"name\":\"First Model\",
  \"language\":\"en-US\",
  \"description\":\"First custom voice model\"}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  name: 'First Model',
  language: 'en-US',
  description: 'First custom voice model'
};

text_to_speech.createCustomization(params, function(error, customization) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(customization, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

CustomVoiceModel model = service.createCustomVoiceModel("First Model", "en-US",
  "First custom voice model").execute();
System.out.println(model);

Response

Returns a single Java CustomVoiceModel object that includes the customization ID of the new custom model. The information is the same as that described for the JSON CustomizationID object.

CustomizationID (Java CustomVoiceModel object)
Name Description
customization_id string The GUID of the new custom voice model.

Response codes

Status Description
201 Created The custom voice model was successfully created.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid parameter 'name' in request
  • Required parameter 'name' is missing
  • Invalid header value for 'header'
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException The specified customizationId is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


{
  "customization_id": "51e996ea-86ca-482e-b7ec-0f31c34e5ee9"
}

Update a custom model

Updates information for the specified custom voice model. You can update metadata such as the name and description of the voice model. You can also update the words in the model and their translations. Adding a new translation for a word that already exists in a custom model overwrites the word's existing translation. A custom model can contain no more than 20,000 entries. You must use credentials for the instance of the service that owns a model to update it.


POST /v1/customizations/{customization_id}

updateCustomization(params, callback())

ServiceCall<Void> updateCustomVoiceModel(CustomVoiceModel model)

Request

Parameter Type Description
Content-Type query string The type of the input, application/json.
customization_id path string The GUID of the custom voice model to be updated. You must make the request with service credentials created for the instance of the service that owns the custom model.
body body object A CustomVoiceUpdate object that provides the information to be updated for the specified custom voice model.
Name Description
customization_id string The GUID of the custom voice model to be updated. You must make the request with service credentials created for the instance of the service that owns the custom model.
name string A new name for the custom voice model.
description string A new description for the custom voice model.
words object[ ] An array of Word objects that provides information about the words to be added or updated for the custom voice model. Pass an empty array to make no additions or updates.
Parameter Description
model object A Java CustomVoiceModel object that provides the information that is to be updated for the custom voice model. The object can provide the same information as a JSON CustomVoiceUpdate object. You must make the request with service credentials created for the instance of the service that owns the custom model.
CustomVoiceUpdate (Java CustomVoiceModel object)
Name Description
name string A new name for the custom voice model.
description string A new description for the custom voice model.
words object[ ] An array of Word objects A List of Java CustomTranslation objects that provides information about the words to be added or updated for the custom voice model.

Example request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--data "{\"name\":\"First Model Update\",
  \"description\":\"First custom voice model update\",
  \"words\":[
    {\"word\":\"NCAA\", \"translation\":\"N C double A\"},
    {\"word\":\"iPhone\", \"translation\":\"I phone\"}
  ]}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}',
  name: 'First Model Update',
  description: 'First custom voice model update',
  words: [{word: 'NCAA', translation: 'N C double A'},
    {word: 'iPhone', translation: 'I phone'}]
};

text_to_speech.updateCustomization(params, function(error) {
  if (error)
    console.log('Error:', error);
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

CustomVoiceModel model = new CustomVoiceModel();
model.setId({customizationId});
model.setName("First Model Update");
model.setDescription("First custom voice model update");
model.setCustomTranslations
  ((List<CustomTranslation>) Arrays.asList
    (new CustomTranslation("NCAA", "N C double A"),
     new CustomTranslation("iPhone", "I phone")));
service.updateCustomVoiceModel(model).execute();

Response

No response body.

Response codes

Status Description
200 OK The custom voice model was successfully updated.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure. Specific messages include
  • Invalid parameter 'name' in request
  • Invalid value for 'customization_id'
  • For word: 'word', <phoneme alphabet="alphabet" ph="translation"></phoneme> is not a standard SSML format
  • In SSML: <phoneme alphabet="ipa" ph="translation"></phoneme>, attribute 'ph' is not a standard IPA format
  • In SSML: <phoneme alphabet="ibm" ph="translation"></phoneme>, attribute 'ph' is not a standard SPR format
  • Invalid part_of_speech name
  • Invalid header value for 'header'
  • Invalid request
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure. (HTTP response code 400.)
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

List custom models

Lists metadata such as the name and description for all custom voice models that are owned by an instance of the service. Specify a language to list the voice models for that language only. To see the words in addition to the metadata for a specific voice model, use the List a voice model method. To see the words in a custom model, use the List custom words method. You must use credentials for the instance of the service that owns a model to list information about it.


GET /v1/customizations

getCustomizations(params, callback())

ServiceCall<List<CustomVoiceModel>> getCustomVoiceModels(String language)

Request

Parameter Type Description
language query string The language for which custom voice models owned by the requesting service credentials are to be returned:
  • de-DE
  • en-GB
  • en-US
  • es-ES
  • es-LA
  • es-US
  • fr-FR
  • it-IT
  • ja-JP
  • pt-BR
Omit the parameter to see all custom voice models owned by the requesting service credentials.
Parameter Description
language string The language for which custom voice models owned by the requesting service credentials are to be returned:
  • de-DE
  • en-GB
  • en-US
  • es-ES
  • es-LA
  • es-US
  • fr-FR
  • it-IT
  • ja-JP
  • pt-BR
Omit the parameter Specify null to see all custom voice models owned by the requesting service credentials.

Example request


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

text_to_speech.getCustomizations(null, function(error, customizations) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(customizations, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

List<CustomVoiceModel> models = service.getCustomVoiceModels(null).execute();
System.out.println(models);

Response

Customizations
Name Description
customizations object[ ] An array of Customization objects that provides information about all custom voice models owned by the requesting service credentials. The array is empty if the requester owns no custom models.

Returns a List of Java CustomVoiceModel objects owned by the requesting service credentials. Each object provides the same information as a JSON Customization object. The list is empty if the requester owns no custom models.

Customization (Java CustomVoiceModel object)
Name Description
customization_id string The GUID of the custom voice model.
name string The name of the custom voice model.
language string The language of the custom voice model; for example, en-US for US English.
owner string The GUID of the service credentials for the instance of the service that owns the custom voice model.
created string The date and time in Coordinated Universal Time (UTC) at which the custom voice model was created. The value is provided in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
last_modified string The date and time in Coordinated Universal Time (UTC) at which the custom voice model was last modified. Equals created when a new voice model is first added but has yet to be changed. The value is provided in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
description string The description of the custom voice model.

Response codes

Status Description
200 OK The request succeeded.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'language'
  • Invalid header value for 'header'
  • Input parameter 'parameter' is invalid
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


{
  "customizations": [
    {
      "owner": "53fd7517-af0d-849d-801b-6e042a5d2f22",
      "language": "en-US",
      "created": "2016-07-15T19:15:17.926Z",
      "customization_id": "a4df11a9-7cf9-48e8-8319-08fb7c3b1aa8",
      "name": "Second Model",
      "description": "Second custom voice model",
      "last_modified": "2016-07-15T19:15:17.926Z"
    },
    {
      "owner": "53fd7517-af0d-849d-801b-6e042a5d2f22",
      "language": "en-US",
      "created": "2016-07-15T18:12:31.743Z",
      "customization_id": "53506a62-6861-41f5-9a44-352047edcf6f",
      "name": "First Model Update",
      "description": "First custom voice model update",
      "last_modified": "2016-07-15T18:23:50.912Z"
    }
  ]
}

[
  {
    "customization_id": "450f285f-f97f-47af-ad86-99d004629ecb",
    "name": "Second Model",
    "description": "Second custom voice model",
    "language": "en-US",
    "owner": "35df7157-fad0-498c-912c-6e429f5c1e11",
    "created": "2017-01-23T16:00:33.111",
    "last_modified": "2017-01-23T16:00:33.114"
  },
  {
    "customization_id": "d76ea7bb-cc91-4591-a9fb-aabf048dcc61",
    "name": "First Model Update",
    "description": "First custom voice model update",
    "language": "en-US",
    "owner": "35df7157-fad0-498c-912c-6e429f5c1e11",
    "created": "2017-01-23T16:00:32.893",
    "last_modified": "2017-01-23T16:00:35.619"
  }
]

List a custom model

Lists all information about a specified custom voice model. In addition to metadata such as the name and description of the voice model, the output includes the words and their translations as defined in the model. To see just the metadata for a voice model, use the List voice models method. You must use credentials for the instance of the service that owns a model to list information about it.


GET /v1/customizations/{customization_id}

getCustomization(params, callback())

ServiceCall<CustomVoiceModel> getCustomVoiceModel(CustomVoiceModel model)
ServiceCall<CustomVoiceModel> getCustomVoiceModel(String customizationId)

Request

Parameter Type Description
customization_id path string The GUID of the custom voice model about which information is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.
Parameter Description
customization_id string The GUID of the custom voice model about which information is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.
Parameter Description
model object The Java CustomVoiceModel object that is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.

You must provide either the model or the customizationId parameter.
customizationId string The GUID of the custom voice model that is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.

You must provide either the model or the customizationId parameter.

Example request


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}'
};

text_to_speech.getCustomization(params, function(error, customization) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(customization, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

CustomVoiceModel model = new CustomVoiceModel();
model.setId({customizationId});
model = service.getCustomVoiceModel(model).execute();
System.out.println(model);

Response

Returns a single Java CustomVoiceModel object. The information is the same as that described for the JSON CustomizationWords object.

CustomizationWords (Java CustomVoiceModel object)
Name Description
customization_id string The GUID of the custom voice model.
name string The name of the custom voice model.
language string The language of the custom voice model:
  • de-DE
  • en-GB
  • en-US
  • es-ES
  • es-LA
  • es-US
  • fr-FR
  • it-IT
  • ja-JP
  • pt-BR
owner string The GUID of the service credentials for the instance of the service that owns the custom voice model.
created string The date and time in Coordinated Universal Time (UTC) at which the custom voice model was created. The value is provided in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD). The string is derived from a Java Date object.
last_modified string The date and time in Coordinated Universal Time (UTC) at which the custom voice model was last modified. Equals created when a new voice model is first added but has yet to be changed. The value is provided in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD). The string is derived from a Java Date object.
description string A description of the custom voice model.
words object[ ] An array of WordList objects that lists the words from the custom voice model. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The array is empty if the custom model contains no words. A List of Java CustomTranslation objects that lists the words from the custom voice model. Each object provides the same information as a JSON WordList object. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The list is empty if the custom model contains no words.

Response codes

Status Description
200 OK The request succeeded.
304 Not Modified The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'customization_id'
  • Invalid header value for 'header'
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
ServiceResponseException The requested resource has not been modified since the time specified by the If-Modified-Since header, as documented in the HTTP specification. (HTTP response code 304.)
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException The specified model or customizationId is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


{
  "customization_id": "d76ea7bb-cc91-4591-a9fb-aabf048dcc61",
  "name": "First Model Update",
  "description": "First custom voice model update",
  "language": "en-US",
  "owner": "35df7157-fad0-498c-912c-6e429f5c1e11",
  "created": "2017-01-23T16:00:32.893",
  "last_modified": "2017-01-23T16:00:35.619",
  "words": [
    {
      "word": "NCAA",
      "translation": "N C double A"
    },
    {
      "word": "iPhone",
      "translation": "I phone"
    }
  ]
}

Delete a custom model

Deletes the specified custom voice model. You must use credentials for the instance of the service that owns a model to delete it.


DELETE /v1/customizations/{customization_id}

deleteCustomization(params, callback())

ServiceCall<Void> deleteCustomVoiceModel(CustomVoiceModel model)

Request

Parameter Type Description
customization_id path string The GUID of the custom voice model that is to be deleted. You must make the request with service credentials created for the instance of the service that owns the custom model.
Parameter Description
customization_id string The GUID of the custom voice model that is to be deleted. You must make the request with service credentials created for the instance of the service that owns the custom model.
Parameter Description
model object The Java CustomVoiceModel object that is to be deleted. You must make the request with service credentials created for the instance of the service that owns the custom model.

Example request


curl -X DELETE -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}'
};

text_to_speech.deleteCustomization(params, function(error) {
  if (error)
    console.log('Error:', error);
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

service.deleteCustomVoiceModel({model}).execute();

Response

No response body.

Response codes

Status Description
204 No Content The custom voice model was successfully deleted.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'customization_id'
  • Invalid header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Custom words

Add custom words

Adds one or more words and their translations to the specified custom voice model. Adding a new translation for a word that already exists in a custom model overwrites the word's existing translation. A custom model can contain no more than 20,000 entries. You must use credentials for the instance of the service that owns a model to add words to it.


POST /v1/customizations/{customization_id}/words

addWords(params, callback())

ServiceCall<Void> addWords(CustomVoiceModel model, CustomTranslation... translations)
ServiceCall<Void> saveWords(CustomVoiceModel model, CustomTranslation... translations) DEPRECATED

Request

Parameter Type Description
Content-Type query string The type of the input, application/json.
customization_id path string The GUID of the custom voice model that is to be updated. You must make the request with service credentials created for the instance of the service that owns the custom model.
body body object A WordsAdd object that provides one or more words that are to be added to the custom voice model and the translation for each specified word.
WordsAdd
Name Description
words object[ ] An array of Word objects that provides information about the words to be added to the custom voice model.
Parameter Description
customization_id string The GUID of the custom voice model that is to be updated. You must make the request with service credentials created for the instance of the service that owns the custom model.
words object[ ] An array of Word objects that provides information about the words to be added to the custom voice model.
Word
Name Description
word string A word to be added or updated for the custom voice model.
translation string The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
part_of_speech string Japanese only. The part of speech for the word:
  • Josi (Joshi; participle)
  • Mesi (Meishi; noun)
  • Kigo (Kigou; symbol)
  • Gobi (Gobi; inflection)
  • Dosi (Doushi; verb)
  • Jodo (Jodoushi; auxiliary verb)
  • Koyu (Koyuumeishi; proper noun)
  • Stbi (Setsubiji; suffix)
  • Suji (Suuji; numeral)
  • Kedo (Keiyodoushi; adjective verb)
  • Fuku (Fukishi; adverb)
  • Keyo (Keiyoshi; adjective verb)
  • Stto (Settoji; prefix)
  • Reta (Rentaishi; determiner)
  • Stzo (Setsuzokushi; conjunction)
  • Kato (Kantoushi; interjection)
  • Hoka (Hoka; other)
The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see Working with Japanese entries.
Parameter Description
model object The Java CustomVoiceModel object to which words are to be added. You must make the request with service credentials created for the instance of the service that owns the custom model.
translations object... A comma-separated list of one or more Java CustomTranslation objects that provides information about the words to be added to the custom voice model.
Java CustomTranslation object
Name Description
word string A word to be added or updated for the custom voice model.
translation string The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
partOfSpeech CustomTranslation.PartOfSpeech Japanese only. The part of speech for the word:
  • PartOfSpeech.JOSI (Joshi; participle)
  • PartOfSpeech.MESI (Meishi; noun)
  • PartOfSpeech.KIGO (Kigou; symbol)
  • PartOfSpeech.GOBI (Gobi; inflection)
  • PartOfSpeech.DOSI (Doushi; verb)
  • PartOfSpeech.JODO (Jodoushi; auxiliary verb)
  • PartOfSpeech.KOYU (Koyuumeishi; proper noun)
  • PartOfSpeech.STBI (Setsubiji; suffix)
  • PartOfSpeech.SUJI (Suuji; numeral)
  • PartOfSpeech.KEDO (Keiyodoushi; adjective verb)
  • PartOfSpeech.FUKU (Fukishi; adverb)
  • PartOfSpeech.KEYO (Keiyoshi; adjective verb)
  • PartOfSpeech.STTO (Settoji; prefix)
  • PartOfSpeech.RETA (Rentaishi; determiner)
  • PartOfSpeech.STZO (Setsuzokushi; conjunction)
  • PartOfSpeech.KATO (Kantoushi; interjection)
  • PartOfSpeech.HOKA (Hoka; other)
The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see Working with Japanese entries.
Constructors:

Example request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--data "{\"words\":[
  {\"word\":\"EEE\", \"translation\":\"<phoneme alphabet=\\\"ibm\\\" ph=\\\"tr1Ipxl.1i\\\"></phoneme>\"},
  {\"word\":\"IEEE\", \"translation\":\"<phoneme alphabet=\\\"ibm\\\" ph=\\\"1Y.tr1Ipxl.1i\\\"></phoneme>\"}
  ]}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}/words"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}',
  words: [
    {word: 'EEE', translation: '<phoneme alphabet="ibm" ph="tr1Ipxl.1i"></phoneme>'},
    {word: 'IEEE', translation: '<phoneme alphabet="ibm" ph="1Y.tr1Ipxl.1i"></phoneme>'}
  ]
};

text_to_speech.addWords(params, function(error) {
  if (error)
    console.log('Error:', error);
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

service.addWords({model},
  new CustomTranslation("EEE", "<phoneme alphabet=\"ibm\" ph=\"tr1Ipxl.1i\"></phoneme>"),
  new CustomTranslation("IEEE", "<phoneme alphabet=\"ibm\" ph=\"1Y.tr1Ipxl.1i\"></phoneme>"))
.execute();

Response

An empty response body: {}.

No response body.

Response codes

Status Description
200 OK The words were successfully added to the custom voice model.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure. Specific messages include
  • Invalid parameter 'name' in request
  • Invalid value for 'customization_id'
  • In SSML: <phoneme alphabet="ipa" ph="translation"></phoneme>, attribute 'ph' is not a standard IPA format
  • In SSML: <phoneme alphabet="ibm" ph="translation"></phoneme>, attribute 'ph' is not a standard SPR format
  • <phoneme alphabet="alphabet" ph="translation"></phoneme> is not a standard SSML format
  • Invalid part_of_speech name
  • Part of speech is supported for ja-JP language only
  • Invalid header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure. (HTTP response code 400.)
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Add a custom word

Adds a single word and its translation to the specified custom voice model. Adding a new translation for a word that already exists in a custom model overwrites the word's existing translation. A custom model can contain no more than 20,000 entries. You must use credentials for the instance of the service that owns a model to add a word to it.


PUT /v1/customizations/{customization_id}/words/{word}

addWord(params, callback())

ServiceCall<Void> addWord(CustomVoiceModel model, CustomTranslation translation)

Request

Parameter Type Description
Content-Type query string The type of the input, application/json.
customization_id path string The GUID of the custom voice model that is to be updated. You must make the request with service credentials created for the instance of the service that owns the custom model.
word path string The word that is to be added or updated for the custom voice model.
body body object A Translation object that provides the translation for the word.
Translation
Name Description
translation string The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
part_of_speech string Japanese only. The part of speech for the word:
  • Josi (Joshi; participle)
  • Mesi (Meishi; noun)
  • Kigo (Kigou; symbol)
  • Gobi (Gobi; inflection)
  • Dosi (Doushi; verb)
  • Jodo (Jodoushi; auxiliary verb)
  • Koyu (Koyuumeishi; proper noun)
  • Stbi (Setsubiji; suffix)
  • Suji (Suuji; numeral)
  • Kedo (Keiyodoushi; adjective verb)
  • Fuku (Fukishi; adverb)
  • Keyo (Keiyoshi; adjective verb)
  • Stto (Settoji; prefix)
  • Reta (Rentaishi; determiner)
  • Stzo (Setsuzokushi; conjunction)
  • Kato (Kantoushi; interjection)
  • Hoka (Hoka; other)
The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see Working with Japanese entries.
Parameter Description
customization_id string The GUID of the custom voice model that is to be updated. You must make the request with service credentials created for the instance of the service that owns the custom model.
word string The word that is to be added or updated for the custom voice model.
translation string The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
Parameter Description
model object The Java CustomVoiceModel object to which a word is to be added. You must make the request with service credentials created for the instance of the service that owns the custom model.
translation object A Java CustomTranslation object that provides information about the word to be added to the custom voice model.

Example request


curl -X PUT -u "{username}":"{password}"
--header "Content-Type: application/json"
--data "{\"translation\":\"ackles\"}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}/words/ACLs"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}',
  word: 'ACls',
  translation: 'ackles'
};

text_to_speech.addWord(params, function(error) {
  if (error)
    console.log('Error:', error);
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

service.addWord({model}, new CustomTranslation("ACLs", "ackles")).execute();

Response

No response body.

Response codes

Status Description
200 OK The word was successfully added to the custom voice model.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure. Specific messages include
  • Invalid parameter 'name' in request
  • Invalid value for 'customization_id'
  • Required parameter 'translation' is missing
  • In SSML: <phoneme alphabet="ipa" ph="translation"></phoneme>, attribute 'ph' is not a standard IPA format
  • In SSML: <phoneme alphabet="ibm" ph="translation"></phoneme>, attribute 'ph' is not a standard SPR format
  • <phoneme alphabet="alphabet" ph="translation"></phoneme> is not a standard SSML format
  • Invalid part_of_speech name
  • Part of speech is supported for ja-JP language only
  • Invalid header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. If the request fails SSML validation, the description of the error explains the failure. (HTTP response code 400.)
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

List custom words

Lists all of the words and their translations for the specified custom voice model. The output shows the translations as they are defined in the model. You must use credentials for the instance of the service that owns a model to query information about its words.


GET /v1/customizations/{customization_id}/words

getWords(params, callback())

ServiceCall<List<CustomTranslation>> getWords(CustomVoiceModel model)

Request

Parameter Type Description
customization_id path string The GUID of the custom voice model whose words are to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.
Parameter Description
customization_id string The GUID of the custom voice model whose words are to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.
Parameter Description
model object The Java CustomVoiceModel object whose words are to be listed. You must make the request with service credentials created for the instance of the service that owns the custom model.

Example request


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}/words"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}'
};

text_to_speech.getWords(params, function(error, words) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(words, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

List<CustomTranslation> words = service.getWords({model}).execute();
System.out.println(words);

Response

WordsList
Name Description
words object[ ] An array of WordList objects that lists the words from the custom voice model. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The array is empty if the custom model contains no words.

Returns a List of Java CustomTranslation objects. Each object provides the same information as a JSON WordList object. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The list is empty if the custom model contains no words.

WordList (Java CustomTranslation object)
Name Description
word string A word from the custom voice model.
translation string The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
part_of_speech string Japanese only. The part of speech for the word. The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see Working with Japanese entries.

Response codes

Status Description
200 OK The request succeeded.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'customization_id'
  • Invalid header value for 'header'
  • Dictionary format error if the custom voice model contains no words
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


{
  "words": [
    {
      "word": "ACLs",
      "translation": "ackles"
    },
    {
      "word": "EEE",
      "translation": "<phoneme alphabet="ibm" ph="tr1Ipxl.1i"></phoneme>"
    },
    {
      "word": "IEEE",
      "translation": "<phoneme alphabet="ibm" ph="1Y.tr1Ipxl.1i"></phoneme>"
    },
    {
      "word": "NCAA",
       "translation": "N C double A"
    },
    {
      "word": "iPhone",
      "translation": "I phone"
    }
  ]
}

[
  {
    "word": "ACLs",
    "translation": "ackles"
  },
  {
    "word": "EEE",
    "translation": "<phoneme alphabet="ibm" ph="tr1Ipxl.1i"></phoneme>"
  },
  {
    "word": "IEEE",
    "translation": "<phoneme alphabet="ibm" ph="1Y.tr1Ipxl.1i"></phoneme>"
  },
  {
    "word": "NCAA",
     "translation": "N C double A"
  },
  {
    "word": "iPhone",
    "translation": "I phone"
  }
]

List a custom word

Returns the translation for a single word from the specified custom model. The output shows the translation as it is defined in the model. You must use credentials for the instance of the service that owns a model to query information about its words.


GET /v1/customizations/{customization_id}/words/{word}

getWord(params, callback())

ServiceCall<CustomTranslation> getWord(CustomVoiceModel model, String word)

Request

Parameter Type Description
customization_id path string The GUID of the custom voice model that contains the word that is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.
word path string The word that is to be returned from the custom voice model.
Parameter Description
customization_id string The GUID of the custom voice model that contains the word that is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model.
model object The Java CustomVoiceModel object that contains the word that is to be returned. You must make the request with the service credentials of the model's owner.
word string The word that is to be returned from the custom voice model.

Example request


curl -X GET -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}/words/ACLs"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}',
  word: 'ACLs'
};

text_to_speech.getWord(params, function(error, word) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(word, null, 2));
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

CustomTranslation translation = service.getWord({model}, "ACLs").execute();
System.out.println(translation);

Response

Returns a single Java CustomTranslation object. The information is the same as that described for the JSON WordTranslation object.

WordTranslation (Java CustomTranslation object)
Name Description
translation string The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
part_of_speech string Japanese only. The part of speech for the word. The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see Working with Japanese entries.

Response codes

Status Description
200 OK The request succeeded.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'customization_id'
  • Word: word not found in customization_id: customization_id
  • Invalid header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


{
  "translation": "ackles"
}

Delete a custom word

Deletes a single word from the specified custom voice model. You must use credentials for the instance of the service that owns a model to delete its words.


DELETE /v1/customizations/{customization_id}/words/{word}

deleteWord(params, callback())

ServiceCall<Void> deleteWord(CustomVoiceModel model, String word)
ServiceCall<Void> deleteWord(CustomVoiceModel model, CustomTranslation translation)

Request

Parameter Type Description
customization_id path string The GUID of the custom voice model from which the word is to be deleted. You must make the request with service credentials created for the instance of the service that owns the custom model.
word path string The word that is to be deleted from the custom voice model.
Parameter Description
customization_id string The GUID of the custom voice model from which the word is to be deleted. You must make the request with service credentials created for the instance of the service that owns the custom model.
word string The word that is to be deleted from the custom voice model.
Parameter Description
model object The Java CustomVoiceModel object from which a word is to be deleted. You must make the request with the service credentials of the model's owner.
word string The word that is to be deleted from the custom voice model.

You must provide either the word or the translation parameter.
translation object A Java CustomTranslation object that specifies the word that is to be deleted from the custom voice model. You need to specify only the word for the object; you can specify null for the other parameters.

You must provide either the word or the translation parameter.

Example request


curl -X DELETE -u "{username}":"{password}"
"https://stream.watsonplatform.net/text-to-speech/api/v1/customizations/{customization_id}/words/ACLs"

var TextToSpeechV1 = require('watson-developer-cloud/text-to-speech/v1');
var text_to_speech = new TextToSpeechV1 ({
  username: '{username}',
  password: '{password}'
});

var params = {
  'customization_id': '{customization_id}',
  word: 'ACLs'
};

text_to_speech.deleteWord(params, function(error) {
  if (error)
    console.log('Error:', error);
});

TextToSpeech service = new TextToSpeech();
service.setUsernameAndPassword("{username}", "{password}");

service.deleteWord({model}, "ACLs").execute();

Response

No response body.

Response codes

Status Description
204 No Content The word was successfully deleted from the custom voice model.
400 Bad Request A required input parameter is null or a specified input parameter or header value is invalid or not supported. Specific messages include
  • Invalid value for 'customization_id'
  • Word: word not found in customization_id: customization_id
  • Invalid header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requesting service credentials:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Exceptions thrown

Exception Description
BadRequestException A required input parameter is null or a specified input parameter is invalid or not supported. (HTTP response code 400.)
UnauthorizedException The specified model is invalid for the requesting service credentials. (HTTP response code 401.)