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.

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.5.3</version>
</dependency>

Gradle


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

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 Using the Text to Speech service.

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 Obtaining 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 Using tokens with Watson services.

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, Bluemix collects data from all requests and uses the data to improve the Watson services. If you do not want to share your data, you can disable request logging by setting the X-Watson-Learning-Opt-Out header to true for each request. Data is not collected for any request that includes this header. setting the X-Watson-Learning-Opt-Out parameter to true when you create the service instance. Data is not collected for any calls by that instance of the service. setting the X-Watson-Learning-Opt-Out header to true when you create the service instance. Data is not collected for any calls by that instance of the service. For more information, see Controlling request logging for Watson services.


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 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 indicate 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 can throw the following common exceptions.

Common exceptions thrown

Exception Description
IllegalArgumentException An illegal argument was passed to a method that accepts one or more arguments.
UnauthorizedException Access is denied due to invalid credentials. (HTTP response code 401.)

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 voice's name, language, and gender, among other things. 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.

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.)
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. 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 the service credentials of the model's owner. 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 the service credentials of the model's owner. 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

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 requester:
  • 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.)
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;codecs=opus (the default)
  • audio/wav
  • audio/flac
  • 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;codecs=opus (the default)
  • audio/wav
  • audio/flac
  • 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 the service credentials of the model's owner. 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;codecs=opus (the default)
  • audio/wav
  • audio/flac
  • 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 the service credentials of the model's owner. 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. If false (the default), data is collected. 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)
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 the service credentials of the model's owner. 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.)
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 the service credentials of the model's owner. 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. If true, no data is collected; if false (the default), data is collected for the request and results. 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;codecs=opus
  • audio/wav
  • audio/flac
  • 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 the service credentials of the model's owner. 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 the service credentials of the model's owner. 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 the service credentials of the model's owner. 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 requester:
  • 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 that is owned by the requesting user.

Creates a new custom voice model or updates an existing custom model:

  • To create a new empty custom model, specify at least a name for the new model. The requesting user owns the new model.

  • To update an existing custom model, specify the customization ID for the model that is to be updated along with new values for the model's name, description, or both. Only the owner of a custom voice model can use this method to update the model.

The method returns the customization ID of the model and the values for any fields of the model that are set or updated by the request.


POST /v1/customizations

createCustomization(params, callback())

ServiceCall<CustomVoiceModel> saveCustomVoiceModel(CustomVoiceModel model)

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
description string A description of the new custom voice model.
Name Description
customization_id string The GUID of the custom voice model. The parameter is required to update an existing custom model. When creating a new custom model, omit the parameter.
name string The name of the custom voice model. The parameter is required to create a new custom model. When updating an existing custom model, the parameter is optional.
language string The language of the 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
When updating an existing custom model, omit this parameter. Do not use the parameter to change the language of an existing model.
description string A description of the custom voice model.

Example request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--data "{\"name\":\"cURL Test\",
  \"language\":\"en-US\",
  \"description\":\"Customization test via cURL\"}"
"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 cURL Test',
  language: 'en-US',
  description: 'First customization test via cURL'
};

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

Example request for create model


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

CustomVoiceModel model = new CustomVoiceModel();
model.setName("First cURL Test");
model.setLanguage("en-US");
model.setDescription("First customization test via cURL");

model = service.saveCustomVoiceModel(model).execute();
String customization_id = model.getId();
System.out.println(model);

Example request for update model


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

CustomVoiceModel model = new CustomVoiceModel();
model.setId("{customization_id}");
model.setName("First cURL Test Update");
model.setDescription("First customization test via cURL update");

model = service.saveCustomVoiceModel(model).execute();
System.out.println(model);

Response

CustomizationID
Name Description
customization_id string The GUID of the new custom voice model.
CustomModel (Java CustomVoiceModel object)
Name Description
customization_id string The GUID of the custom voice model.
name string The name of the custom voice model. Returned only if the name is specified with the request.
language string The language of the custom voice model; for example, en-US for US English. Returned only if the language is specified with the request.
description string The description of the custom voice model. Returned only if the description is specified with the request.

Response codes

Status Description
200 OK 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 customization_id is invalid for the requester. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


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

Example response for create model


{
  "customization_id": "d76ea7bb-cc91-4591-a9fb-aabf048dcc61",
  "name": "First cURL Test",
  "description": "First customization test via cURL",
  "language": "en-US"
}

Example response for update model


{
  "customization_id": "d76ea7bb-cc91-4591-a9fb-aabf048dcc61",
  "name": "First cURL Test Update",
  "description": "First customization test via cURL update"
}

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. Only the owner of a custom voice model can use this method to update the model.

To update the name or description of an existing custom voice model, use the saveCustomVoiceModel method that is used to create a new model; see Create a voice model.


POST /v1/customizations/{customization_id}

updateCustomization(params, callback())

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 the service credentials of the model's owner.
body body object A CustomVoiceUpdate object that provides the information to be updated for the specified custom voice model.
CustomVoiceUpdate
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 WordUpdate objects that provides a list of words and their translations to be added to or updated in the custom voice model. Pass an empty array to make no additions or updates.
Name Description
customization_id string The GUID of the custom voice model to be updated. You must make the request with the service credentials of the model's owner.
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 WordUpdate objects that provides a list of words and their translations to be added to or updated in the custom voice model. Pass an empty array to make no additions or updates.
WordUpdate
Name Description
word string A word to be added to or updated in 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.

Example request


curl -X POST -u "{username}":"{password}"
--header "Content-Type: application/json"
--data "{\"name\":\"First cURL Test Update\",
  \"description\":\"First customization test via cURL 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 cURL Test Update',
  description: 'First customization test via cURL Update',
  words: [{word: 'NCAA', translation: 'N C double A'}, {word: 'iPhone', translation: 'I phone'}]
};

text_to_speech.updateCustomization(params, function(error, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log('Updated custom model: ', '{customization_id}');
});

Response

No response body.

Response codes

Status Description
201 Created 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 header value for 'header'
  • Invalid request
401 Unauthorized The specified customization_id is invalid for the requester:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

List custom models

Lists metadata such as the name and description for all custom voice models that are owned by the requesting user. 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. Only the owner of a custom voice model can use this method to list information about a model.

Lists metadata such as the name and description for all custom voice models that are owned by the requesting user for a specified language. Only the owner of a custom voice model can use this method to list information about the model. To see the words in a custom model, use the List words method.


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 requester 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 requester.
Parameter Description
language string The language for which custom voice models owned by the requester 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 requester.
Parameter Description
language string The language for which custom voice models owned by the requester are to be returned:
  • de-DE
  • en-GB
  • en-US
  • es-ES
  • es-LA
  • es-US
  • fr-FR
  • it-IT
  • ja-JP
  • pt-BR

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(response, null, 2));
});

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

List<CustomVoiceModel> models = service.getCustomVoiceModels("en-US").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 requester. The array is empty if the user owns no custom models.

Returns a List of Java CustomVoiceModel objects. The list is empty if the user 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 owner of 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.)
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 cURL Test",
      "description": "Second customization test via cURL",
      "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 cURL Test Update",
      "description": "First customization test via cURL update",
      "last_modified": "2016-07-15T18:23:50.912Z"
    }
  ]
}

[
  {
    "customization_id": "450f285f-f97f-47af-ad86-99d004629ecb",
    "name": "Second cURL Test",
    "description": "Second customization test via cURL",
    "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 cURL Test Update",
    "description": "First customization test via cURL 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 in the model and their translations as defined in the model. To see just the metadata for a voice model, use the List voice models method. Only the owner of a custom voice model can use this method to query information about the model.

Lists metadata such as the name and description for a specified custom voice model. Only the owner of a custom voice model can use this method to query information about the model. To see the words in a custom model, use the List words method.


GET /v1/customizations/{customization_id}

getCustomization(params, callback())

ServiceCall<CustomVoiceModel> getCustomVoiceModel(String id)

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 the service credentials of the model's owner.
Parameter Description
customization_id string The GUID of the custom voice model about which information is to be returned. that is to be returned. You must make the request with the service credentials of the model's owner.

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(response, null, 2));
});

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

CustomVoiceModel model = service.getCustomVoiceModel("{customization_id}").execute();
System.out.println(model);

Response

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

CustomizationWords
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 owner of 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 A description of the custom voice model.
words object[ ] An array of WordList objects that lists the words and their translations 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.

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'
401 Unauthorized The specified customization_id is invalid for the requester:
  • 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 customization_id is invalid for the requester. (HTTP response code 401.)
InternalServerErrorException The service experienced an internal error. (HTTP response code 500.)

Example response


{
  "owner": "53fd7517-af0d-849d-801b-6e042a5d2f22",
  "created": "2016-07-15T18:12:31.743Z",
  "language": "en-US",
  "last_modified": "2016-07-15T18:23:50.912Z",
  "customization_id": "53506a62-6861-41f5-9a44-352047edcf6f",
  "name": "First cURL Test Update",
  "description": "First customization test via cURL update",
  "words": [
    {
      "word": "NCAA",
      "translation": "N C double A"
    },
    {
      "word": "iPhone",
      "translation": "I phone"
    }
  ]
}

{
  "customization_id": "d76ea7bb-cc91-4591-a9fb-aabf048dcc61",
  "name": "First cURL Test Update",
  "description": "First customization test via cURL 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"
}

Delete a custom model

Deletes the specified custom voice model. Only the owner of a custom voice model can use this method to delete the model.


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 the service credentials of the model's owner.
Parameter Description
customization_id string The GUID of the custom voice model that is to be deleted. You must make the request with the service credentials of the model's owner.
Parameter Description
model object The Java CustomVoiceModel object that is to be deleted. You must make the request with the service credentials of the model's owner.

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log('Deleted custom model:', '{customization_id}');
});

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

service.deleteCustomVoiceModel({model}).execute();
System.out.println("Deleted custom model: " + "{customization_id}");

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 requester:
  • 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.)
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. Only the owner of a custom voice model can use this method to add words to the model.


POST /v1/customizations/{customization_id}/words

addWords(params, callback())

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

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 the service credentials of the model's owner.
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 WordAdd 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 the service credentials of the model's owner.
words object[ ] An array of WordAdd objects that provides information about the words to be added to the custom voice model.
WordAdd
Name Description
word string A word to be added to 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 the service credentials of the model's owner.
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 to 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.

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log('Added words to custom model:', '{customization_id}');
});

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

CustomTranslation translation1 = new CustomTranslation("NCAA", "N C double A");
CustomTranslation translation2 = new CustomTranslation("iPhone", "I phone");
CustomTranslation translation3 = new CustomTranslation("ACLs", "ackles");

service.saveWords({model}, translation1, translation2, translation3).execute();
System.out.println("Added words to custom model: " + "{customization_id}");

Response

No response body.

Response codes

Status Description
201 Created 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 header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requester:
  • 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 requester. (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. Only the owner of a custom voice model can use this method to add a word to the model.

To add a word to a custom voice model, use the saveWords method; see Add words.


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

addWord(params, callback())

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 the service credentials of the model's owner.
word path string The word that is to be added to 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 the service credentials of the model's owner.
word string The word that is to be added to 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.

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log('Added word', params.word, 'to custom model:', '{customization_id}');
});

Response

No response body.

Response codes

Status Description
201 Created 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 header value for 'header'
401 Unauthorized The specified customization_id is invalid for the requester:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

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. Only the owner of a custom voice model can use this method to query information about the model's 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 the service credentials of the model's owner.
Parameter Description
customization_id string The GUID of the custom voice model whose words are to be returned. You must make the request with the service credentials of the model's owner.
Parameter Description
model object The Java CustomVoiceModel object whose words are to be listed. You must make the request with the service credentials of the model's owner.

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(response, 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 and their translations 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.
WordList
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.

Returns a List of Java CustomTranslation objects. The list is empty if the custom model contains no words.

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 requester:
  • 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 requester. (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": "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. Only the owner of a custom voice model can use this method to query information about a word from the model.

Not supported.


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

getWord(params, callback())

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 the service credentials of the model's owner.
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 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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log(JSON.stringify(response, null, 2));
});

Response

WordTranslation
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 requester:
  • Invalid customization_id (id) for user.
500 Internal Server Error The service experienced an internal error.

Example response


{
  "translation": "ackles"
}

Delete a custom word

Deletes a single word from the specified custom voice model. Only the owner of a custom voice model can use this method to delete a word from the model.


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

deleteWord(params, callback())

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 the service credentials of the model's owner.
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 the service credentials of the model's owner.
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.
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 translation.

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, response) {
  if (error)
    console.log('Error:', error);
  else
    console.log('Deleted word from custom model:', '{customization_id}');
});

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

CustomTranslation translation = new CustomTranslation("ACLs", null);
service.deleteWord({model}, translation).execute();
System.out.println("Deleted word from custom model: " + "{customization_id}");

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 requester:
  • 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 requester. (HTTP response code 401.)