--- name: text-to-speech-voices-list title: Listing information about voices description: The IBM Watson® Text to Speech service provides methods for listing information about all of its available voices or about a specific voice. last-updated: 2025-02-18 --- > ## Documentation Index > The table of contents for this documentation set is at https://cloud.ibm.com/docs/text-to-speech?format=markdown > The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt > Use these files to discover more information as needed. # Listing information about voices {: #voices-list} The IBM Watson® Text to Speech service provides methods for listing information about all of its available voices or about a specific voice. {: shortdesc} ## Listing all voices {: #list-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]{: tag-ibm-cloud} ```bash curl -X GET -u "apikey:{apikey}" \ "{url}/v1/voices" ``` {: pre} [IBM Cloud Pak for Data]{: tag-cp4d} [IBM Software Hub]{: tag-teal} ```bash curl -X GET \ --header "Authorization: Bearer {token}" \ "{url}/v1/voices" ``` {: pre} This abbreviated response shows only the first few voices of the response: ```javascript { "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." }, . . . ] } ``` {: codeblock} 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 `` element. The feature was available only for obsolete standard US English voices. You cannot use the `` 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 {: #list-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]{: tag-ibm-cloud} ```bash curl -X GET -u "apikey:{apikey}" \ "{url}/v1/voices/en-US_LisaV3Voice?customization_id=64f4807f-a5f1-5867-924f-7bba1a84fe97" ``` {: pre} [IBM Cloud Pak for Data]{: tag-cp4d} [IBM Software Hub]{: tag-teal} ```bash curl -X GET \ --header "Authorization: Bearer {token}" \ "{url}/v1/voices/en-US_LisaV3Voice?customization_id=64f4807f-a5f1-5867-924f-7bba1a84fe97" ``` {: pre} 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. ```javascript { "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" } } ``` {: codeblock} 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](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customModels&format=markdown#cuModelsQuery).