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

Python
JavaScript
Java
cURL

# List all available voices
voices = client.voices.list()

for voice in voices:
    print(f"{voice.id}: {voice.name}")
    print(f"  Category: {voice.category}")
    print(f"  Languages: {', '.join(voice.supported_languages)}")

// List all available voices
const voices = await client.voices.list();

for (const voice of voices) {
  console.log(`${voice.id}: ${voice.name}`);
  console.log(`  Category: ${voice.category}`);
  console.log(`  Languages: ${voice.supportedLanguages.join(', ')}`);
}

import com.kugelaudio.sdk.Voice;
import java.util.List;

List<Voice> voices = client.voices().list();
for (Voice voice : voices) {
    System.out.printf("%d: %s%n", voice.getId(), voice.getName());
    System.out.printf("  Category: %s%n", voice.getCategory());
    System.out.printf("  Languages: %s%n",
        String.join(", ", voice.getSupportedLanguages()));
}

curl https://api.kugelaudio.com/v1/voices \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

Filter Voices

Python
JavaScript
Java
cURL

# Filter by language
result = client.voices.list(language="de")
german_voices = result.voices

# Get only public voices
result = client.voices.list(include_public=True)

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

// Filter by language
const { voices: germanVoices } = await client.voices.list({ language: 'de' });

// Get only public voices
const { voices: publicVoices } = await client.voices.list({ includePublic: true });

// Limit results
const { voices: first10 } = await client.voices.list({ limit: 10 });

// Paginate
const { voices, total } = await client.voices.list({ limit: 10, offset: 20 });

// Filter by language
VoiceListResponse result = client.voices().list("de", null, null, null);
List<Voice> germanVoices = result.getVoices();

// Paginate
VoiceListResponse page = client.voices().list(null, null, 10, 20);
System.out.printf("Showing %d of %d%n", page.getVoices().size(), page.getTotal());

# Filter by language
curl "https://api.kugelaudio.com/v1/voices?language=de" \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

# Get only public voices
curl "https://api.kugelaudio.com/v1/voices?include_public=true" \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

# Limit results
curl "https://api.kugelaudio.com/v1/voices?limit=10" \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

# Get only cloned voices
curl "https://api.kugelaudio.com/v1/voices?category=cloned" \
  -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 text: {voice.sample_text}")

const voice = await client.voices.get(1071);
console.log(`Voice: ${voice.name}`);
console.log(`Description: ${voice.description}`);
console.log(`Sample text: ${voice.sampleText}`);

Voice voice = client.voices().get(1071);
System.out.printf("Voice: %s%n", voice.getName());
System.out.printf("Description: %s%n", voice.getDescription());
System.out.printf("Sample text: %s%n", voice.getSampleText());

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:

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

// With streaming sessions (for LLM integration)
try (StreamingSession session = client.tts().streamingSession(
        StreamConfig.builder().voiceId(1071).cfgScale(2.0).build())) {
    session.send("Hello!", true);
}

# 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
`name`	string	Human-readable name
`description`	string	Voice description
`category`	string	`premade`, `cloned`, or `generated`
`sex`	string	`male`, `female`, or `neutral`
`age`	string	`young`, `middle_aged`, or `old`
`supported_languages`	list	ISO 639-1 language codes
`sample_text`	string	Sample text for preview
`sample_url`	string	Sample audio URL
`is_public`	bool	Whether the voice is publicly available
`verified`	bool	Whether the voice has been verified

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

Deploy

SDK Reference

API Reference

List Available Voices

Filter Voices

Get Voice Details

Use a Specific Voice

Voice Properties

Next Steps

Voice Cloning

Generate Speech

Streaming

​List Available Voices

​Filter Voices

​Get Voice Details

​Use a Specific Voice

​Voice Properties

​Next Steps

Voice Cloning

Generate Speech

Streaming

List Available Voices

Filter Voices

Get Voice Details

Use a Specific Voice

Voice Properties

Next Steps