Using Voices

KugelAudio provides a variety of premade voices and supports custom voice cloning. This guide covers how to work with voices in your application.

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. total counts the matching public catalog voices; your own matching voices come with every page and are not part of total.

Python
JavaScript
Java
cURL

# 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

Python
JavaScript
Java
cURL

# 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

Python
JavaScript
Java
cURL

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.

Python
JavaScript
Java
cURL

audio = client.tts.generate(
    text="Hello with a specific voice!",
    model_id="kugel-3",
    voice_id=1071,
)

const audio = await client.tts.generate({
  text: 'Hello with a specific voice!',
  modelId: 'kugel-3',
  voiceId: 1071,
});

AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("Hello with a specific voice!")
        .modelId("kugel-3")
        .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",
    "voice_id": 1071
  }' \
  --output output.pcm

Voices work with all generation methods: basic generation, streaming, and streaming sessions.

Python
JavaScript
Java
cURL

# With streaming
for chunk in client.tts.stream(
    text="Streaming with a specific voice.",
    model_id="kugel-3",
    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', voiceId: 1071 },
  { onChunk: (chunk) => playAudio(chunk.audio) }
);

// With streaming
client.tts().stream(
    GenerateRequest.builder("Streaming with a specific voice.")
        .modelId("kugel-3")
        .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",
    "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

Next Steps

Voice Cloning

Create custom voices from audio samples

Generate Speech

Generate audio with your chosen voice

Streaming

Stream audio in real-time

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

List Available Voices

Paginate Voices

Get Voice Details

Use a Specific Voice

Voice Properties

Next Steps

Voice Cloning

Generate Speech

Streaming

​List Available Voices

​Paginate Voices

​Get Voice Details

​Use a Specific Voice

​Voice Properties

​Next Steps

Voice Cloning

Generate Speech

Streaming

List Available Voices

Paginate Voices

Get Voice Details

Use a Specific Voice

Voice Properties

Next Steps