Using Voices
Find and use KugelAudio voices: list the voice catalog, filter it by language, page through results, get voice details and choose a voice for each request.
On this page
KugelAudio provides a variety of premade voices and supports custom voice cloning. This guide covers how to work with voices in your application.
Listen to Voices
Six voices from the public catalog, each rendered with kugel-3.5. The German
voices read "Danke für Ihren Anruf. Ich helfe Ihnen gern, Ihren Termin zu
verschieben." and the English voices read "Thanks for calling. I would be happy
to help you move your appointment." Copy a voice ID and pass it as voice_id
to hear that voice in your own requests. List the voices
to see the whole catalog.
List Available Voices
The listing returns your own voices and the public catalog, one page at a
time (20 by default, up to 100 with limit). Pass language to list only the
voices that speak it. Voices carry BCP-47 tags in supported_languages, and
the filter is case-insensitive: de matches every German accent (de-DE,
de-AT, de-CH), de-AT only Austrian German. Your own voices come first,
then the public catalog, and total counts every matching voice.
# First page of voices (default 20, max 100)
result = client.voices.list()
for voice in result.voices:
print(f"{voice.id}: {voice.name}")
print(f" Languages: {', '.join(voice.supported_languages)}")
# German voices, any accent
german = client.voices.list(language="de")// First page of voices (default 20, max 100)
const result = await client.voices.list();
for (const voice of result.voices) {
console.log(`${voice.id}: ${voice.name}`);
console.log(` Category: ${voice.category}`);
console.log(` Languages: ${voice.supportedLanguages.join(', ')}`);
}
// German voices, any accent
const german = await client.voices.list({ language: 'de' });import com.kugelaudio.sdk.Voice;
import com.kugelaudio.sdk.VoiceListResponse;
VoiceListResponse result = client.voices().list();
for (Voice voice : result.getVoices()) {
System.out.printf("%d: %s%n", voice.getId(), voice.getName());
System.out.printf(" Quality: %s%n", voice.getQuality());
}
// German voices, any accent
VoiceListResponse german = client.voices().list("de", null, 20, 0);curl https://api.kugelaudio.com/v1/voices \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY"
# German voices, any accent
curl "https://api.kugelaudio.com/v1/voices?language=de" \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY"Paginate Voices
# Limit results
result = client.voices.list(limit=10)
# Paginate through all voices
result = client.voices.list(limit=10, offset=20)
print(f"Showing {len(result.voices)} of {result.total} voices")// Limit results
const { voices: first10 } = await client.voices.list({ limit: 10 });
// Paginate
const { voices, total } = await client.voices.list({ limit: 10, offset: 20 });// Paginate: list(language, includePublic, limit, offset).
// The server ignores the first two arguments; pass null.
VoiceListResponse page = client.voices().list(null, null, 10, 20);
System.out.printf("Showing %d of %d%n", page.getVoices().size(), page.getTotal());# Limit results
curl "https://api.kugelaudio.com/v1/voices?limit=10" \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY"Get Voice Details
voice = client.voices.get(voice_id=1071)
print(f"Voice: {voice.name}")
print(f"Description: {voice.description}")
print(f"Sample URL: {voice.sample_url}")const voice = await client.voices.get(1071);
console.log(`Voice: ${voice.name}`);
console.log(`Description: ${voice.description}`);
console.log(`Sample URL: ${voice.sampleUrl}`);import com.kugelaudio.sdk.VoiceDetail;
VoiceDetail voice = client.voices().get(1071);
System.out.printf("Voice: %s%n", voice.getName());
System.out.printf("Sample URL: %s%n", voice.getSampleUrl());curl https://api.kugelaudio.com/v1/voices/1071 \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY"Use a Specific Voice
Pass the voice_id (Python), voiceId (JavaScript), or voice_id JSON field (cURL) when generating speech.
On the raw API (REST and WebSocket), voice_id accepts either the numeric
id or the voice's handle string, and GET /v1/voices/{voice_id} resolves
both. The SDKs take the numeric id.
audio = client.tts.generate(
text="Hello with a specific voice!",
model_id="kugel-3.5",
voice_id=1071,
)const audio = await client.tts.generate({
text: 'Hello with a specific voice!',
modelId: 'kugel-3.5',
voiceId: 1071,
});AudioResponse audio = client.tts().generate(
GenerateRequest.builder("Hello with a specific voice!")
.modelId("kugel-3.5")
.voiceId(1071)
.language("en")
.build()
);curl -X POST https://api.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello with a specific voice!",
"model_id": "kugel-3.5",
"voice_id": 1071
}' \
--output output.pcmVoices work with all generation methods: basic generation, streaming, and streaming sessions.
# With streaming
for chunk in client.tts.stream(
text="Streaming with a specific voice.",
model_id="kugel-3.5",
voice_id=1071,
):
if hasattr(chunk, 'audio'):
play_audio(chunk.audio)
# With streaming sessions (for LLM integration)
async with client.tts.streaming_session(
voice_id=1071,
cfg_scale=2.0,
) as session:
async for chunk in session.send("Hello!"):
play_audio(chunk.audio)// With streaming
await client.tts.stream(
{ text: 'Streaming with a specific voice.', modelId: 'kugel-3.5', voiceId: 1071 },
{ onChunk: (chunk) => playAudio(chunk.audio) }
);// With streaming
client.tts().stream(
GenerateRequest.builder("Streaming with a specific voice.")
.modelId("kugel-3.5")
.voiceId(1071)
.language("en")
.build(),
new StreamCallbacks() {
@Override
public void onChunk(AudioChunk chunk) {
playAudio(chunk.getAudio());
}
}
);
# Stream with a specific voice and pipe to ffplay
curl -X POST https://api.kugelaudio.com/v1/tts/generate \
-H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Streaming with a specific voice.",
"model_id": "kugel-3.5",
"voice_id": 1071
}' \
--no-buffer | ffplay -f s16le -ar 24000 -ac 1 -nodisp -Voice Properties
Each voice includes the following information:
| Property | Type | Description |
|---|---|---|
id | int | Unique voice ID |
voice_id | int | Same value as id for backward compatibility |
handle | string | null | Stable string identifier, when assigned; usable as voice_id on the raw API |
public_id | string | null | Public identifier, when assigned |
name | string | Human-readable name |
description | string | null | Voice description |
category | string | Voice catalog category |
sex | string | null | male, female, or neutral |
age | string | null | Voice age label |
quality | string | Voice quality label |
supported_languages | list | BCP-47 language tags (de-DE, en-GB) |
sample_url | string | null | Sample audio URL |
avatar_url | string | null | Voice avatar URL |