Listing information about voices

Listing all voices

The GET /v1/voices method lists information about all available voices. It takes no arguments and returns a JSON array that is named voices. The array includes a separate object for each voice. The order in which the service returns voices can change from call to call. Do not rely on an alphabetized or static list of voices.

The following example lists all voices that are supported by the service:

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/voices"

IBM Cloud Pak for Data

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/voices"

This abbreviated response shows only the first few voices of the response:

{
  "voices": [
    {
      "name": "en-US_LisaV3Voice",
      "language": "en-US",
      "gender": "female",
      "url": "{url}/v1/voices/en-US_LisaV3Voice",
      "customizable": true,
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Lisa: American English female voice.",
    },
    {
      "name": "es-LA_SofiaV3Voice",
      "language": "es-LA",
      "customizable": true,
      "gender": "female",
      "url": "{url}/v1/voices/es-LA_SofiaV3Voice",
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Sofia: Latin American Spanish (español latinoamericano) female voice."
    },
    {
      "name": "pt-BR_IsabelaV3Voice",
      "language": "pt-BR",
      "customizable": true,
      "gender": "female",
      "url": "{url}/v1/voices/pt-BR_IsabelaV3Voice",
      "supported_features": {
        "voice_transformation": false,
        "custom_pronunciation": true
      },
      "description": "Isabela: Brazilian Portuguese (português brasileiro) female voice."
    },
    . . .
  ]
}

The fields of the voice objects provide the following information:

• name is an identifier for the voice (for example, en-US_LisaV3Voice). Specify this value for the voice parameter of the /v1/synthesize method.
• language specifies the language and region of the voice (for example, en-US).
• gender identifies the voice as male or female.
• url identifies the URL for the voice.
• description provides a brief description of the voice.
• customizable is a boolean value that indicates whether the voice can be customized with the service's customization interface. (This field, which provides the same information as the custom_pronunciation field, is maintained for backward compatibility.)
• supported_features describes the additional service features that are supported by the voice:
  • voice_transformation is a boolean value that indicates whether the voice supported the SSML <voice-transformation> element. The feature was available only for obsolete standard US English voices. You cannot use the <voice-transformation> element with any supported voice.
  • custom_pronunciation is a boolean value that indicates whether the voice can be customized with the service's customization interface.

Listing a specific voice

The GET /v1/voices/{voice} method lists information about a specific voice. It accepts two parameters.

• voice (path parameter, required string) - Identifies the voice for which information is to be returned. You specify a voice by its name (for example, en-US_LisaV3Voice).
• customization_id (query parameter, optional string) - Provides the globally unique identifier (GUID) of a custom model that is defined for the language of the specified voice. If you include a customization ID, you must make the request with credentials for the instance of the service that owns the custom model.

If you omit the customization_id parameter, the method returns JSON output for the specified voice that is identical to the information returned for a voice by the GET /v1/voices method. If you specify a customization_id, the output includes a customization field that provides information about the specified custom model.

The following example returns information about the en-US_LisaV3Voice and the specified custom model:

IBM Cloud

curl -X GET -u "apikey:{apikey}" \
"{url}/v1/voices/en-US_LisaV3Voice?customization_id=64f4807f-a5f1-5867-924f-7bba1a84fe97"

IBM Cloud Pak for Data

curl -X GET \
--header "Authorization: Bearer {token}" \
"{url}/v1/voices/en-US_LisaV3Voice?customization_id=64f4807f-a5f1-5867-924f-7bba1a84fe97"

The attributes of the additional customization field provide metadata information such as the GUID, name, language, and description of the custom model. They also show the credentials of the model's owner, the date and time at which the model was created, and the date and time of its last modification.

{
  "name": "en-US_LisaV3Voice",
  "language": "en-US",
  "gender": "female",
  "url": "{url}/v1/voices/en-US_LisaV3Voice",
  "description": "Lisa: American English female voice.",
  "customizable": true,
  "supported_features": {
    "voice_transformation": false,
    "custom_pronunciation": true
  },
  "customization": {
    "customization_id": "64f4807f-a5f1-5867-924f-7bba1a84fe97",
    "owner": "297cfd08-330a-22ba-93ce-1a73f454dd98",
    "created": "2017-09-16T17:12:31.743Z",
    "name": "Customization test",
    "language": "en-US",
    "description": "Customization test",
    "last_modified": "2017-09-16T17:12:31.743Z"
  }
}

To see the custom words and prompts that the model includes, use the GET /v1/customizations/{customization_id} method. For more information, see Querying a custom model.