Available Voices

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

Voice IDs are used in the speech generation endpoint to specify which voice to use for text-to-speech conversion.

Using the SDK

The Node.js SDK provides a simple way to list available voices:

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();

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.

REST API

You can list available voices using the REST API directly. Here are examples in different languages:

curl -X GET https://api.suonora.com/v1/voices/list \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET https://api.suonora.com/v1/voices/list \
  -H "Authorization: Bearer YOUR_API_KEY"

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}")

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());
        }
    }
}

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();

success

boolean

required

Indicates if the request was successful

voices

array

required

Array of available voice objects

Example Response

{
  "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

Best Practices

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
Caching
- Cache the voice list to reduce API calls
- Update the cache periodically to get new voices
- Store voice IDs for quick reference
Error Handling
- Always check the success flag
- Handle API errors gracefully
- Implement retry logic for temporary failures

For production applications, consider implementing a voice selection interface that allows users to preview and choose voices based on their needs.

Get Started

Essentials

Available Voices

Example Response

Response Codes

Best Practices

Get Started

Essentials

​Example Response

​Response Codes

​Best Practices

Example Response

Response Codes

Best Practices