> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suonora.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Available Voices

> Browse and preview the available voices for text-to-speech conversion.

<Steps title="Listing Available Voices">
  <Step title="Overview">
    The voices endpoint provides a list of all available voices that can be used for text-to-speech conversion. Each voice includes:

    * Voice ID and name
    * Gender and locale
    * Preview audio URL
    * Additional metadata

    <Note>
      Voice IDs are used in the speech generation endpoint to specify which voice to use for text-to-speech conversion.
    </Note>
  </Step>

  <Step title="Using the SDK">
    The Node.js SDK provides a simple way to list available voices:

    ```js
    const Suonora = require('suonora-sdk');

    const suonora = new Suonora({
      apiKey: 'YOUR_API_KEY'
    });

    async function listVoices() {
      try {
        const voices = await suonora.getVoices();

        console.log('--- Available Voices ---');
        voices.forEach(voice => {
          console.log(`\nVoice: ${voice.name} (${voice.id})`);
          console.log(`Gender: ${voice.gender}`);
          console.log(`Locale: ${voice.locale}`);
          console.log(`Preview: ${voice.mp3_preview}`);
        });
      } catch (error) {
        console.error('Error listing voices:', error.message);
      }
    }

    listVoices();
    ```

    <Note type="info">
      The SDK handles authentication and error handling automatically. It's the recommended way to interact with the Suonora API if you're using Node.js.
    </Note>
  </Step>

  <Step title="REST API">
    You can list available voices using the REST API directly. Here are examples in different languages:

    <Tabs>
      <Tab title="curl">
        ```bash
        curl -X GET https://api.suonora.com/v1/voices/list \
          -H "Authorization: Bearer YOUR_API_KEY"
        ```
      </Tab>

      <Tab title="Python">
        ```python
        import requests

        url = "https://api.suonora.com/v1/voices/list"
        headers = {
            "Authorization": "Bearer YOUR_API_KEY"
        }

        try:
            response = requests.get(url, headers=headers)
            response.raise_for_status()
            data = response.json()

            print("--- Available Voices ---")
            for voice in data['voices']:
                print(f"\nVoice: {voice['name']} ({voice['id']})")
                print(f"Gender: {voice['gender']}")
                print(f"Locale: {voice['locale']}")
                print(f"Preview: {voice['mp3_preview']}")

        except requests.exceptions.RequestException as error:
            print(f"Error listing voices: {error}")
        ```
      </Tab>

      <Tab title="Java">
        ```java
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;
        import java.net.URI;
        import org.json.JSONObject;
        import org.json.JSONArray;

        public class VoiceLister {
            public static void main(String[] args) {
                HttpClient client = HttpClient.newHttpClient();
                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://api.suonora.com/v1/voices/list"))
                    .header("Authorization", "Bearer YOUR_API_KEY")
                    .GET()
                    .build();

                try {
                    HttpResponse<String> response = client.send(request,
                        HttpResponse.BodyHandlers.ofString());

                    JSONObject json = new JSONObject(response.body());
                    JSONArray voices = json.getJSONArray("voices");

                    System.out.println("--- Available Voices ---");
                    for (int i = 0; i < voices.length(); i++) {
                        JSONObject voice = voices.getJSONObject(i);
                        System.out.printf("%nVoice: %s (%s)%n",
                            voice.getString("name"),
                            voice.getString("id"));
                        System.out.printf("Gender: %s%n",
                            voice.getString("gender"));
                        System.out.printf("Locale: %s%n",
                            voice.getString("locale"));
                        System.out.printf("Preview: %s%n",
                            voice.getString("mp3_preview"));
                    }

                } catch (Exception e) {
                    System.err.printf("Error listing voices: %s%n", e.getMessage());
                }
            }
        }
        ```
      </Tab>

      <Tab title="JavaScript">
        ```js
        async function listVoices() {
          try {
            const response = await fetch('https://api.suonora.com/v1/voices/list', {
              headers: {
                'Authorization': 'Bearer YOUR_API_KEY'
              }
            });

            if (!response.ok) {
              throw new Error(`HTTP error! status: ${response.status}`);
            }

            const data = await response.json();

            console.log('--- Available Voices ---');
            data.voices.forEach(voice => {
              console.log(`\nVoice: ${voice.name} (${voice.id})`);
              console.log(`Gender: ${voice.gender}`);
              console.log(`Locale: ${voice.locale}`);
              console.log(`Preview: ${voice.mp3_preview}`);
            });
          } catch (error) {
            console.error('Error listing voices:', error.message);
          }
        }

        listVoices();
        ```
      </Tab>
    </Tabs>

    <ResponseField name="success" type="boolean" required>
      Indicates if the request was successful
    </ResponseField>

    <ResponseField name="voices" type="array" required>
      Array of available voice objects

      <Expandable title="Voice Object Fields">
        <ResponseField name="id" type="string" required>
          Unique identifier for the voice (used in speech generation)
        </ResponseField>

        <ResponseField name="name" type="string" required>
          Display name of the voice
        </ResponseField>

        <ResponseField name="gender" type="string" required>
          Gender of the voice (e.g., "Male", "Female")
        </ResponseField>

        <ResponseField name="locale" type="string" required>
          Language and region code (e.g., "en-US", "de-DE")
        </ResponseField>

        <ResponseField name="mp3_preview" type="string" required>
          URL to a short audio preview of the voice
        </ResponseField>
      </Expandable>
    </ResponseField>

    ### Example Response

    ```json
    {
      "success": true,
      "voices": [
        {
          "id": "axel",
          "name": "Axel",
          "gender": "Male",
          "locale": "de-DE",
          "mp3_preview": "https://storage.googleapis.com/suonora-public/voices/Axel.mp3"
        }
      ]
    }
    ```

    ### Response Codes

    <ResponseCode code="200" description="Request was successful" />

    <ResponseCode code="401" description="Unauthorized – API key is missing or invalid" />

    <ResponseCode code="403" description="Forbidden – The API key does not have permission to access this resource" />

    <ResponseCode code="429" description="Too Many Requests – The request rate limit has been exceeded" />

    <ResponseCode code="500" description="Internal Server Error – An unexpected error occurred on the server" />
  </Step>
</Steps>

***

## Best Practices

1. **Voice Selection**

   * Choose voices that match your content's language and region
   * Consider the gender and style that best fits your use case
   * Preview voices before using them in production

2. **Caching**

   * Cache the voice list to reduce API calls
   * Update the cache periodically to get new voices
   * Store voice IDs for quick reference

3. **Error Handling**
   * Always check the `success` flag
   * Handle API errors gracefully
   * Implement retry logic for temporary failures

<Note type="tip">
  For production applications, consider implementing a voice selection interface
  that allows users to preview and choose voices based on their needs.
</Note>

{" "}