Listing all voices">

List voices

GET /v1/voices

Lists all voices available for use with the service. The information includes the name, language, gender, and other details about the voice. The ordering of the list of voices can change from call to call; do not rely on an alphabetized or static list of voices. To see information about a specific voice, use the Get a voice.

See also: Listing all voices

Request

Response

200 - OK. The request succeeded.

voices

array

A list of available voices.

406 - Not Acceptable. The request specified an `Accept` header with an incompatible content type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

415 - Unsupported Media Type. The request specified an unacceptable media type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Listing a specific voice.">

Get a voice

GET /v1/voices/{voice}

Gets information about the specified voice. The information includes the name, language, gender, and other details about the voice. Specify a customization ID to obtain information for a custom model that is defined for the language of the specified voice. To list information about all available voices, use the List voices method.

See also: Listing a specific voice.

Request

Path Parameters

voice

Required *

string

The voice for which information is to be returned.

Query Parameters

customization_id

string

The customization ID (GUID) of a custom model for which information is to be returned. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to see information about the specified voice with no customization.

Response

200 - OK. The request succeeded.

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 as the voice identifier in all requests.

language

string

The language and region of the voice (for example, `en-US`).

description

string

A textual description of the voice.

customizable

boolean

If `true`, the voice can be customized; if `false`, the voice cannot be customized. (Same as `custom_pronunciation`; maintained for backward compatibility.)

supported_features

SupportedFeatures

Additional service features that are supported with the voice.

customization

object

Information about an existing custom model.

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'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ({id}) for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

406 - Not Acceptable. The request specified an `Accept` header with an incompatible content type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

415 - Unsupported Media Type. The request specified an unacceptable media type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

The HTTP interface.

Audio formats (accept types)

The service can return audio in the following formats (MIME types).

Where indicated, you can optionally specify the sampling rate (`rate`) of the audio. You must specify a sampling rate for the `audio/alaw`, `audio/l16`, and `audio/mulaw` formats. A specified sampling rate must lie in the range of 8 kHz to 192 kHz. Some formats restrict the sampling rate to certain values, as noted.
For the `audio/l16` format, you can optionally specify the endianness (`endianness`) of the audio: `endianness=big-endian` or `endianness=little-endian`.

Use the `Accept` header or the `accept` parameter to specify the requested format of the response audio. If you omit an audio format altogether, the service returns the audio in Ogg format with the Opus codec (`audio/ogg;codecs=opus`). The service always returns single-channel audio.

`audio/alaw` - You must specify the `rate` of the audio.
`audio/basic` - The service returns audio with a sampling rate of 8000 Hz.
`audio/flac` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/l16` - You must specify the `rate` of the audio. You can optionally specify the `endianness` of the audio. The default endianness is `little-endian`.
`audio/mp3` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for for all other voices.
`audio/mpeg` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/mulaw` - You must specify the `rate` of the audio.
`audio/ogg` - The service returns the audio in the `vorbis` codec. You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=opus` - You can optionally specify the `rate` of the audio. Only the following values are valid sampling rates: `48000`, `24000`, `16000`, `12000`, or `8000`. If you specify a value other than one of these, the service returns an error. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/wav` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/webm` - The service returns the audio in the `opus` codec. The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=opus` - The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.

For more information about specifying an audio format, including additional details about some of the formats, see Using audio formats.

Note: By default, the service returns audio in the Ogg audio format with the Opus codec (`audio/ogg;codecs=opus`). However, the Ogg audio format is not supported with the Safari browser. If you are using the service with the Safari browser, you must use the `Accept` request header or the `accept` query parameter specify a different format in which you want the service to return the audio.

Warning messages

If a request includes invalid query parameters, the service returns a `Warnings` response header that provides messages about the invalid parameters. 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.">

Synthesize audio (GET)

GET /v1/synthesize

Synthesizes text to audio that is spoken in the specified voice. The service bases its understanding of the language for the input text on the specified voice. Use a voice that matches the language of the input text.

The method accepts a maximum of 8 KB of input, which includes the input text and the URL and headers. The 8 KB limit includes any SSML tags that you specify. The service returns the synthesized audio stream as an array of bytes.

See also: The HTTP interface.

Audio formats (accept types)

The service can return audio in the following formats (MIME types).

Where indicated, you can optionally specify the sampling rate (`rate`) of the audio. You must specify a sampling rate for the `audio/alaw`, `audio/l16`, and `audio/mulaw` formats. A specified sampling rate must lie in the range of 8 kHz to 192 kHz. Some formats restrict the sampling rate to certain values, as noted.
For the `audio/l16` format, you can optionally specify the endianness (`endianness`) of the audio: `endianness=big-endian` or `endianness=little-endian`.

`audio/alaw` - You must specify the `rate` of the audio.
`audio/basic` - The service returns audio with a sampling rate of 8000 Hz.
`audio/flac` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/l16` - You must specify the `rate` of the audio. You can optionally specify the `endianness` of the audio. The default endianness is `little-endian`.
`audio/mp3` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for for all other voices.
`audio/mpeg` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/mulaw` - You must specify the `rate` of the audio.
`audio/ogg` - The service returns the audio in the `vorbis` codec. You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=opus` - You can optionally specify the `rate` of the audio. Only the following values are valid sampling rates: `48000`, `24000`, `16000`, `12000`, or `8000`. If you specify a value other than one of these, the service returns an error. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/wav` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/webm` - The service returns the audio in the `opus` codec. The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=opus` - The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.

For more information about specifying an audio format, including additional details about some of the formats, see Using audio formats.

Warning messages

Request

Path Parameters

Query Parameters

accept

string

The requested format (MIME type) of the audio. You can use the `accept` parameter or the `Accept` header to specify the audio format. URL-encode the argument to the `accept` parameter; for example, `audio/mulaw;rate=8000` becomes `audio%2Fmulaw%3Brate%3D8000`. For more information about specifying an audio format, see Audio formats (accept types) in the method description.

voice

string

The voice to use for speech synthesis. If you omit the `voice` parameter, the service uses the US English `en-US_MichaelV3Voice` by default.

For IBM Cloud Pak for Data, if you do not install the `en-US_MichaelV3Voice`, you must either specify a voice with the request or specify a new default voice for your installation of the service.

See also:

customization_id

string

The customization ID (GUID) of a custom model to use for the synthesis. If a custom model is specified, it works only if it matches the language of the indicated voice. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customization.

text

Required *

string

The text to synthesize. Specify either plain text or a subset of SSML. SSML is an XML-based markup language that provides text annotation for speech-synthesis applications. You must URL-encode the input text. Pass a maximum of 8 KB of input, which includes the input text and the URL and headers. For more information, see

spell_out_mode

string

For German voices, indicates how the service is to spell out strings of individual letters. To indicate the pace of the spelling, specify one of the following values:

`default` - The service reads the characters at the rate at which it synthesizes speech for the request. You can also omit the parameter entirely to achieve the default behavior.
`singles` - The service reads the characters one at a time, with a brief pause between each character.
`pairs` - The service reads the characters two at a time, with a brief pause between each pair.
`triples` - The service reads the characters three at a time, with a brief pause between each triplet.

For more information, see Specifying how strings are spelled out.

rate_percentage

integer

The percentage change from the default speaking rate of the voice that is used for speech synthesis. Each voice has a default speaking rate that is optimized to represent a normal rate of speech. The parameter accepts an integer that represents the percentage change from the voice's default rate:

Specify a signed negative integer to reduce the speaking rate by that percentage. For example, -10 reduces the rate by ten percent.
Specify an unsigned or signed positive integer to increase the speaking rate by that percentage. For example, 10 and +10 increase the rate by ten percent.
Specify 0 or omit the parameter to get the default speaking rate for the voice.

The parameter affects the rate for an entire request.

For more information, see Modifying the speaking rate.

pitch_percentage

integer

The percentage change from the default speaking pitch of the voice that is used for speech synthesis. Each voice has a default speaking pitch that is optimized to represent a normal tone of voice. The parameter accepts an integer that represents the percentage change from the voice's default tone:

Specify a signed negative integer to lower the voice's pitch by that percentage. For example, -5 reduces the tone by five percent.
Specify an unsigned or signed positive integer to increase the voice's pitch by that percentage. For example, 5 and +5 increase the tone by five percent.
Specify 0 or omit the parameter to get the default speaking pitch for the voice.

The parameter affects the pitch for an entire request.

For more information, see Modifying the speaking pitch.

Response

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. Examples of specific messages include

`prompt_id '{prompt_id}' not found in custom model '{customization_id}'` if you attempt to use a nonexistent or deleted custom prompt.
`<express-as> is not supported in the current voice` if you attempt to use the `<express-as>` element with a voice that is not one of the expressive neural voices or if you specify an illegal value for the `style` attribute of the element.
`Tag <express-as> is missing required attribute->type` if you omit the `style` attribute from the `<express-as>` element.
`Emphasis level {level} is not supported` if you specify an illegal value for the `level` attribute of the `<emphasis>` element.

If the request fails SSML validation, the description of the error explains the failure. For example, `<prosody> with attribute volume is not supported in the current voice`. For more information, see SSML validation.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

404 - Not Found. The specified voice does not exist or, for IBM Cloud Pak for Data, the `voice` parameter was not specified but the default voice is not installed. The message is `Model '{voice}' not found`.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

406 - Not Acceptable. The request specified an incompatible content type or failed to specify a required sampling rate.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

415 - Unsupported Media Type. The request specified an unacceptable media type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

The HTTP interface.

Audio formats (accept types)

The service can return audio in the following formats (MIME types).

Where indicated, you can optionally specify the sampling rate (`rate`) of the audio. You must specify a sampling rate for the `audio/alaw`, `audio/l16`, and `audio/mulaw` formats. A specified sampling rate must lie in the range of 8 kHz to 192 kHz. Some formats restrict the sampling rate to certain values, as noted.
For the `audio/l16` format, you can optionally specify the endianness (`endianness`) of the audio: `endianness=big-endian` or `endianness=little-endian`.

`audio/alaw` - You must specify the `rate` of the audio.
`audio/basic` - The service returns audio with a sampling rate of 8000 Hz.
`audio/flac` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/l16` - You must specify the `rate` of the audio. You can optionally specify the `endianness` of the audio. The default endianness is `little-endian`.
`audio/mp3` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for for all other voices.
`audio/mpeg` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/mulaw` - You must specify the `rate` of the audio.
`audio/ogg` - The service returns the audio in the `vorbis` codec. You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=opus` - You can optionally specify the `rate` of the audio. Only the following values are valid sampling rates: `48000`, `24000`, `16000`, `12000`, or `8000`. If you specify a value other than one of these, the service returns an error. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/wav` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/webm` - The service returns the audio in the `opus` codec. The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=opus` - The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.

For more information about specifying an audio format, including additional details about some of the formats, see Using audio formats.

Warning messages

Synthesize audio

POST /v1/synthesize

The method accepts a maximum of 5 KB of input text in the body of the request, and 8 KB for the URL and headers. The 5 KB limit includes any SSML tags that you specify. The service returns the synthesized audio stream as an array of bytes.

See also: The HTTP interface.

Audio formats (accept types)

The service can return audio in the following formats (MIME types).

Where indicated, you can optionally specify the sampling rate (`rate`) of the audio. You must specify a sampling rate for the `audio/alaw`, `audio/l16`, and `audio/mulaw` formats. A specified sampling rate must lie in the range of 8 kHz to 192 kHz. Some formats restrict the sampling rate to certain values, as noted.
For the `audio/l16` format, you can optionally specify the endianness (`endianness`) of the audio: `endianness=big-endian` or `endianness=little-endian`.

`audio/alaw` - You must specify the `rate` of the audio.
`audio/basic` - The service returns audio with a sampling rate of 8000 Hz.
`audio/flac` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/l16` - You must specify the `rate` of the audio. You can optionally specify the `endianness` of the audio. The default endianness is `little-endian`.
`audio/mp3` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for for all other voices.
`audio/mpeg` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/mulaw` - You must specify the `rate` of the audio.
`audio/ogg` - The service returns the audio in the `vorbis` codec. You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=opus` - You can optionally specify the `rate` of the audio. Only the following values are valid sampling rates: `48000`, `24000`, `16000`, `12000`, or `8000`. If you specify a value other than one of these, the service returns an error. The default sampling rate is 48,000 Hz.
`audio/ogg;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.
`audio/wav` - You can optionally specify the `rate` of the audio. The default sampling rate is 24,000 Hz for Natural voices and 22,050 Hz for all other voices.
`audio/webm` - The service returns the audio in the `opus` codec. The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=opus` - The service returns audio with a sampling rate of 48,000 Hz.
`audio/webm;codecs=vorbis` - You can optionally specify the `rate` of the audio. The default sampling rate is 48,000 Hz.

For more information about specifying an audio format, including additional details about some of the formats, see Using audio formats.

Warning messages

Request

Request Body

Text

text

Required *

string

The text to synthesize.

Path Parameters

Query Parameters

accept

string

voice

string

The voice to use for speech synthesis. If you omit the `voice` parameter, the service uses the US English `en-US_MichaelV3Voice` by default.

For IBM Cloud Pak for Data, if you do not install the `en-US_MichaelV3Voice`, you must either specify a voice with the request or specify a new default voice for your installation of the service.

See also:

customization_id

string

spell_out_mode

string

For German voices, indicates how the service is to spell out strings of individual letters. To indicate the pace of the spelling, specify one of the following values:

`default` - The service reads the characters at the rate at which it synthesizes speech for the request. You can also omit the parameter entirely to achieve the default behavior.
`singles` - The service reads the characters one at a time, with a brief pause between each character.
`pairs` - The service reads the characters two at a time, with a brief pause between each pair.
`triples` - The service reads the characters three at a time, with a brief pause between each triplet.

For more information, see Specifying how strings are spelled out.

rate_percentage

integer

Specify a signed negative integer to reduce the speaking rate by that percentage. For example, -10 reduces the rate by ten percent.
Specify an unsigned or signed positive integer to increase the speaking rate by that percentage. For example, 10 and +10 increase the rate by ten percent.
Specify 0 or omit the parameter to get the default speaking rate for the voice.

The parameter affects the rate for an entire request.

For more information, see Modifying the speaking rate.

pitch_percentage

integer

Specify a signed negative integer to lower the voice's pitch by that percentage. For example, -5 reduces the tone by five percent.
Specify an unsigned or signed positive integer to increase the voice's pitch by that percentage. For example, 5 and +5 increase the tone by five percent.
Specify 0 or omit the parameter to get the default speaking pitch for the voice.

The parameter affects the pitch for an entire request.

For more information, see Modifying the speaking pitch.

Response

200 - OK. The request succeeded.

400 - Bad Request. A required input parameter is null or a specified input parameter or header value is invalid. Examples of specific messages include

`prompt_id '{prompt_id}' not found in custom model '{customization_id}'` if you attempt to use a nonexistent or deleted custom prompt.
`<express-as> is not supported in the current voice` if you attempt to use the `<express-as>` element with a voice that is not one of the expressive neural voices or if you specify an illegal value for the `style` attribute of the element.
`Tag <express-as> is missing required attribute->type` if you omit the `style` attribute from the `<express-as>` element.
`Emphasis level {level} is not supported` if you specify an illegal value for the `level` attribute of the `<emphasis>` element.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

404 - Not Found. The specified voice does not exist or, for IBM Cloud Pak for Data, the `voice` parameter was not specified but the default voice is not installed. The message is `Model '{voice}' not found`.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

406 - Not Acceptable. The request specified an incompatible content type or failed to specify a required sampling rate.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

415 - Unsupported Media Type. The request specified an unacceptable media type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Querying a word from a language.">

Get pronunciation

GET /v1/pronunciation

Gets 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 model to see the translation for that model.

See also: Querying a word from a language.

Request

Path Parameters

Query Parameters

text

Required *

string

The word for which the pronunciation is requested.

voice

string

A voice that specifies the language in which the pronunciation is to be returned. If you omit the `voice` parameter, the service uses the US English `en-US_MichaelV3Voice` by default. All voices for the same language (for example, `en-US`) return the same translation.

For IBM Cloud Pak for Data, if you do not install the `en-US_MichaelV3Voice`, you must either specify a voice with the request or specify a new default voice for your installation of the service.

See also: Using the default voice.

format

string

The phoneme format in which to return the pronunciation. Omit the parameter to obtain the pronunciation in the default format.

customization_id

string

The customization ID (GUID) of a custom model for which the pronunciation is to be returned. The language of a specified custom model must match the language of the specified voice. If the word is not defined in the specified custom model, the service returns the default translation for the custom model's language. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to see the translation for the specified voice with no customization.

Response

200 - OK. The request succeeded.

pronunciation

string

The pronunciation of the specified text in the requested voice and format. If a custom model is specified, the pronunciation also reflects that custom model.

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'`
`Customization language {language} does not match the language {language} for voice {voice}`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

404 - Not Found. The specified voice does not exist or, for IBM Cloud Pak for Data, the `voice` parameter was not specified but the default voice is not installed. The message is `Model '{voice}' not found`.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

406 - Not Acceptable. The request specified an `Accept` header with an incompatible content type.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Creating a custom model.">

Create a custom model

POST /v1/customizations

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

See also: Creating a custom model.

Request

Request Body

CreateCustomModel

A `CreateCustomModel` object that contains information about the new custom model.

name

Required *

string

The name of the new custom model. Use a localized name that matches the language of the custom model. Use a name that describes the purpose of the custom model, such as `Medical custom model` or `Legal custom model`. Use a name that is unique among all custom models that you own.

Include a maximum of 256 characters in the name. Do not use backslashes, slashes, colons, equal signs, ampersands, or question marks in the name.

language

string

The language of the new custom model. You create a custom model for a specific language, not for a specific voice. A custom model can be used with any voice for its specified language. Omit the parameter to use the the default language, `en-US`.

description

string

A recommended description of the new custom model. Use a localized description that matches the language of the custom model. Include a maximum of 128 characters in the description.

Response

201 - Created. The custom model was successfully created.

customization_id

string

The customization ID (GUID) of the custom model. The Create a custom model method returns only this field. It does not not return the other fields of this object.

name

string

The name of the custom model.

language

string

The language identifier of the custom model (for example, `en-US`).

owner

string

The GUID of the credentials for the instance of the service that owns the custom model.

created

string

The date and time in Coordinated Universal Time (UTC) at which the custom 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 model was last modified. The `created` and `updated` fields are equal when a model is first added but has yet to be updated. The value is provided in full ISO 8601 format (`YYYY-MM-DDThh:mm:ss.sTZD`).

description

string

The description of the custom model.

words

array

An array of `Word` objects that lists the words and their translations from the custom model. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The array is empty if no words are defined for the custom model. This field is returned only by the Get a custom model method.

prompts

array

An array of `Prompt` objects that provides information about the prompts that are defined for the specified custom model. The array is empty if no prompts are defined for the custom model. This field is returned only by the Get a custom model method.

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}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Querying all custom models.">

List custom models

GET /v1/customizations

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

See also: Querying all custom models.

Request

Path Parameters

Query Parameters

language

string

The language for which custom models that are owned by the requesting credentials are to be returned. Omit the parameter to see all custom models that are owned by the requester.

Response

200 - OK. The request succeeded.

customizations

array

An array of `CustomModel` objects that provides information about each available custom model. The array is empty if the requesting credentials own no custom models (if no language is specified) or own no custom models for the specified language.

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`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Updating a custom model

Adding words to a Japanese custom model

Understanding customization">

Update a custom model

POST /v1/customizations/{customization_id}

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

You can define sounds-like or phonetic translations for words. A sounds-like translation consists of one or more words that, when combined, sound like the word. Phonetic translations are based on the SSML phoneme format for representing a word. You can specify them in standard International Phonetic Alphabet (IPA) representation

&lt;code&gt;&amp;lt;phoneme alphabet&#x3D;&quot;ipa&quot; ph&#x3D;&quot;t&amp;#601;m&amp;#712;&amp;#593;to&quot;&amp;gt;&amp;lt;/phoneme&amp;gt;&lt;/code&gt;

or in the proprietary IBM Symbolic Phonetic Representation (SPR)

&lt;code&gt;&amp;lt;phoneme alphabet&#x3D;&quot;ibm&quot; ph&#x3D;&quot;1gAstroEntxrYFXs&quot;&amp;gt;&amp;lt;/phoneme&amp;gt;&lt;/code&gt;

See also:

Request

Request Body

UpdateCustomModel

An `UpdateCustomModel` object that contains information that is to be updated for the custom model.

name

string

A new name for the custom model.

description

string

A new description for the custom model.

words

array

An array of `Word` objects that provides the words and their translations that are to be added or updated for the custom model. Pass an empty array to make no additions or updates.

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

Query Parameters

Response

200 - OK. The custom 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; for more information, see SSML validation. Specific messages include

`Invalid parameter '{name}' in request`
`Invalid value for 'customization_id'`
<code>For word: '{word}', <phoneme alphabet="{alphabet}" ph="{translation}"></phoneme> is not a standard SSML format</code>
<code>In SSML: <phoneme alphabet="ipa" ph="{translation}"></phoneme>, attribute 'ph' is not a standard IPA format</code>
<code>In SSML: <phoneme alphabet="ibm" ph="{translation}"></phoneme>, attribute 'ph' is not a standard SPR format</code>
`Invalid part_of_speech name`
`Part of speech is supported for ja-JP language only`
`Invalid header value for '{header}'`
`Invalid request`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Querying a custom model.">

Get a custom model

GET /v1/customizations/{customization_id}

Gets all information about a specified custom model. In addition to metadata such as the name and description of the custom model, the output includes the words and their translations that are defined for the model, as well as any prompts that are defined for the model. To see just the metadata for a model, use the List custom models method.

See also: Querying a custom model.

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

Query Parameters

Response

200 - OK. The request succeeded.

customization_id

string

The customization ID (GUID) of the custom model. The Create a custom model method returns only this field. It does not not return the other fields of this object.

name

string

The name of the custom model.

language

string

The language identifier of the custom model (for example, `en-US`).

owner

string

The GUID of the credentials for the instance of the service that owns the custom model.

created

string

The date and time in Coordinated Universal Time (UTC) at which the custom model was created. The value is provided in full ISO 8601 format (`YYYY-MM-DDThh:mm:ss.sTZD`)

last_modified

string

description

string

The description of the custom model.

words

array

prompts

array

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}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Deleting a custom model.">

Delete a custom model

DELETE /v1/customizations/{customization_id}

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

See also: Deleting a custom model.

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

Query Parameters

Response

204 - No Content. The custom 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}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Adding multiple words to a custom model

Adding words to a Japanese custom model

Understanding customization">

Add custom words

POST /v1/customizations/{customization_id}/words

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

&lt;code&gt;&amp;lt;phoneme alphabet&#x3D;&quot;ipa&quot; ph&#x3D;&quot;t&amp;#601;m&amp;#712;&amp;#593;to&quot;&amp;gt;&amp;lt;/phoneme&amp;gt;&lt;/code&gt;

or in the proprietary IBM Symbolic Phonetic Representation (SPR)

&lt;code&gt;&amp;lt;phoneme alphabet&#x3D;&quot;ibm&quot; ph&#x3D;&quot;1gAstroEntxrYFXs&quot;&amp;gt;&amp;lt;/phoneme&amp;gt;&lt;/code&gt;

See also:

Request

Request Body

Words

words

Required *

array

The Add custom words method accepts an array of `Word` objects. Each object provides a word that is to be added or updated for the custom model and the word's translation.

The List custom words method returns an array of `Word` objects. Each object shows a word and its translation from the custom 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.

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

Query Parameters

Response

200 - OK. The words were successfully added to the custom 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; for more information, see SSML validation. Specific messages include

`Invalid parameter '{name}' in request`
`Invalid value for 'customization_id'`
<code><phoneme alphabet="{alphabet}" ph="{translation}"></phoneme> is not a standard SSML format</code>
<code>In SSML: <phoneme alphabet="ipa" ph="{translation}"></phoneme>, attribute 'ph' is not a standard IPA format</code>
<code>In SSML: <phoneme alphabet="ibm" ph="{translation}"></phoneme>, attribute 'ph' is not a standard SPR format</code>
`Invalid part_of_speech name`
`Part of speech is supported for ja-JP language only`
`Invalid header value for '{header}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Querying all words from a custom model.">

List custom words

GET /v1/customizations/{customization_id}/words

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

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

Query Parameters

Response

200 - OK. The request succeeded.

words

array

The Add custom words method accepts an array of `Word` objects. Each object provides a word that is to be added or updated for the custom model and the word's translation.

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 model contains no words)

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Adding a single word to a custom model

Adding words to a Japanese custom model

Understanding customization">

Add a custom word

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

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

&lt;code&gt;&amp;lt;phoneme alphabet&#x3D;&quot;ipa&quot; ph&#x3D;&quot;t&amp;#601;m&amp;#712;&amp;#593;to&quot;&amp;gt;&amp;lt;/phoneme&amp;gt;&lt;/code&gt;

or in the proprietary IBM Symbolic Phonetic Representation (SPR)

&lt;code&gt;&amp;lt;phoneme alphabet&#x3D;&quot;ibm&quot; ph&#x3D;&quot;1gAstroEntxrYFXs&quot;&amp;gt;&amp;lt;/phoneme&amp;gt;&lt;/code&gt;

See also:

Request

Request Body

Translation

The translation for the word that is to be added or updated.

translation

Required *

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 translation or as an IBM SPR translation. A sounds-like is 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.

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

word

Required *

string

The word that is to be added or updated for the custom model.

Query Parameters

Response

200 - OK. The word was successfully added to the custom 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; for more information, see SSML validation. Specific messages include

`Invalid parameter '{name}' in request`
`Invalid value for 'customization_id'`
`Required parameter 'translation' is missing`
<code><phoneme alphabet="{alphabet}" ph="{translation}"></phoneme> is not a standard SSML format</code>
<code>In SSML: <phoneme alphabet="ipa" ph="{translation}"></phoneme>, attribute 'ph' is not a standard IPA format</code>
<code>In SSML: <phoneme alphabet="ibm" ph="{translation}"></phoneme>, attribute 'ph' is not a standard SPR format</code>
`Invalid part_of_speech name`
`Part of speech is supported for ja-JP language only`
`Invalid header value for '{header}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Querying a single word from a custom model.">

Get a custom word

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

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

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

word

Required *

string

The word that is to be queried from the custom model.

Query Parameters

Response

200 - OK. The request succeeded.

translation

string

part_of_speech

string

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}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Deleting a word from a custom model.">

Delete a custom word

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

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

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

word

Required *

string

The word that is to be deleted from the custom model.

Query Parameters

Response

204 - No Content. The word was successfully deleted from the custom 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}'`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `customization_id` is invalid for the requesting credentials:

`Invalid customization_id ('{id}') for user`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Get a custom model method. That method provides complete details about a specified custom model, including its language, owner, custom words, and more. Custom prompts are supported only for use with US English custom models and voices.

List custom prompts

GET /v1/customizations/{customization_id}/prompts

Important: The Tune by Example feature is deprecated. The APIs for creating new prompts or speaker models are no longer supported. Existing prompts and speaker models will continue to function; however, this feature is planned to be fully removed in a future release.

Lists information about all custom prompts that are defined for a custom model. The information includes the prompt ID, prompt text, status, and optional speaker ID for each prompt of the custom model. You must use credentials for the instance of the service that owns the custom model. The same information about all of the prompts for a custom model is also provided by the Get a custom model method. That method provides complete details about a specified custom model, including its language, owner, custom words, and more. Custom prompts are supported only for use with US English custom models and voices.

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

Query Parameters

Response

200 - OK. The request succeeded.

prompts

array

An array of `Prompt` objects that provides information about the prompts that are defined for the specified custom model. The array is empty if no prompts are defined for the custom model.

400 - Bad Request. The request failed. Possible failure causes include:

Invalid service credentials were passed with the request.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Get a custom prompt

GET /v1/customizations/{customization_id}/prompts/{prompt_id}

Gets information about a specified custom prompt for a specified custom model. The information includes the prompt ID, prompt text, status, and optional speaker ID for each prompt of the custom model. You must use credentials for the instance of the service that owns the custom model. Custom prompts are supported only for use with US English custom models and voices.

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

prompt_id

Required *

string

The identifier (name) of the prompt.

Query Parameters

Response

200 - OK. The request succeeded.

prompt

string

The user-specified text of the prompt.

prompt_id

string

The user-specified identifier (name) of the prompt.

status

string

The status of the prompt:

`processing`: The service received the request to add the prompt and is analyzing the validity of the prompt.
`available`: The service successfully validated the prompt, which is now ready for use in a speech synthesis request.
`failed`: The service's validation of the prompt failed. The status of the prompt includes an `error` field that describes the reason for the failure.

error

string

If the status of the prompt is `failed`, an error message that describes the reason for the failure. The field is omitted if no error occurred.

speaker_id

string

The speaker ID (GUID) of the speaker for which the prompt was defined. The field is omitted if no speaker ID was specified.

400 - Bad Request. The request failed. Possible failure causes include:

Invalid service credentials were passed with the request.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The request failed. Possible failure causes include:

The specified `customization_id` is invalid for the requesting credentials.
The specified `prompt_id` is invalid for the requesting credentials or for the specified custom model.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Delete a custom prompt

DELETE /v1/customizations/{customization_id}/prompts/{prompt_id}

Deletes an existing custom prompt from a custom model. The service deletes the prompt with the specified ID. You must use credentials for the instance of the service that owns the custom model from which the prompt is to be deleted.

Caution: Deleting a custom prompt elicits a 400 response code from synthesis requests that attempt to use the prompt. Make sure that you do not attempt to use a deleted prompt in a production application. Custom prompts are supported only for use with US English custom models and voices.

Request

Path Parameters

customization_id

Required *

string

The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.

prompt_id

Required *

string

The identifier (name) of the prompt that is to be deleted.

Query Parameters

Response

204 - No Content. The prompt was deleted successfully.

400 - Bad Request. The request failed. Possible failure causes include:

Invalid service credentials were passed with the request.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The request failed. Possible failure causes include:

The specified `customization_id` is invalid for the requesting credentials.
The specified `prompt_id` is invalid for the requesting credentials.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

List speaker models

GET /v1/speakers

Lists information about all speaker models that are defined for a service instance. The information includes the speaker ID and speaker name of each defined speaker. You must use credentials for the instance of a service to list its speakers. Speaker models and the custom prompts with which they are used are supported only for use with US English custom models and voices.

Request

Response

200 - OK. The request succeeded.

speakers

array

An array of `Speaker` objects that provides information about the speakers for the service instance. The array is empty if the service instance has no speakers.

400 - Bad Request. The request failed. Possible failure causes include:

Invalid service credentials were passed with the request.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Get a speaker model

GET /v1/speakers/{speaker_id}

Gets information about all prompts that are defined by a specified speaker for all custom models that are owned by a service instance. The information is grouped by the customization IDs of the custom models. For each custom model, the information lists information about each prompt that is defined for that custom model by the speaker. You must use credentials for the instance of the service that owns a speaker model to list its prompts. Speaker models and the custom prompts with which they are used are supported only for use with US English custom models and voices.

Request

Path Parameters

speaker_id

Required *

string

The speaker ID (GUID) of the speaker model. You must make the request with service credentials for the instance of the service that owns the speaker model.

Query Parameters

Response

200 - OK. The request succeeded.

customizations

array

An array of `SpeakerCustomModel` objects. Each object provides information about the prompts that are defined for a specified speaker in the custom models that are owned by a specified service instance. The array is empty if no prompts are defined for the speaker.

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.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

400 - Bad Request. The request failed. Possible failure causes include:

Invalid service credentials were passed with the request.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `speaker_id` is invalid for the requesting credentials.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Delete a speaker model

DELETE /v1/speakers/{speaker_id}

Deletes an existing speaker model from the service instance. The service deletes the enrolled speaker with the specified speaker ID. You must use credentials for the instance of the service that owns a speaker model to delete the speaker.

Any prompts that are associated with the deleted speaker are not affected by the speaker's deletion. The prosodic data that defines the quality of a prompt is established when the prompt is created. A prompt is static and remains unaffected by deletion of its associated speaker. However, the prompt cannot be resubmitted or updated with its original speaker once that speaker is deleted. Speaker models and the custom prompts with which they are used are supported only for use with US English custom models and voices.

Request

Path Parameters

speaker_id

Required *

string

The speaker ID (GUID) of the speaker model. You must make the request with service credentials for the instance of the service that owns the speaker model.

Query Parameters

Response

204 - No Content. The speaker model was deleted successfully.

400 - Bad Request. The request failed. Possible failure causes include:

Invalid service credentials were passed with the request.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

401 - Unauthorized. The specified `speaker_id` is invalid for the requesting credentials.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

Information security.">

Delete labeled data

DELETE /v1/user_data

Deletes all data that is associated with a specified customer ID. The method deletes all data for the customer ID, regardless of the method by which the information was added. The method has no effect if no data is associated with the customer ID. You must issue the request with credentials for the same instance of the service that was used to associate the customer ID with the data. You associate a customer ID with data by passing the `X-Watson-Metadata` header with a request that passes the data.

Note: If you delete an instance of the service from the service console, all data associated with that service instance is automatically deleted. This includes all custom models and word/translation pairs, and all data related to speech synthesis requests.

See also: Information security.

Request

Path Parameters

Query Parameters

customer_id

Required *

string

The customer ID for which all data is to be deleted.

Response

200 - OK. The deletion request was successfully submitted.

400 - Bad Request. The request did not pass a customer ID:

`No customer ID found in the request`

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

500 - Internal Server Error. The service experienced an internal error.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.

503 - Service Unavailable. The service is currently unavailable.

error

string

Description of the problem.

code

integer

HTTP response code.

code_description

string

Response message.