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
Python
Java
JavaScript
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();
Indicates if the request was successful
Array of available voice objects
Unique identifier for the voice (used in speech generation)
Display name of the voice
Gender of the voice (e.g., “Male”, “Female”)
Language and region code (e.g., “en-US”, “de-DE”)
URL to a short audio preview of the voice
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.
