Skip to content
KugelAudioDocs

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.

0:00 / --:--
Antonia MeierGermankugel-3.5
0:00 / --:--
Samantha FerrisEnglishkugel-3.5
0:00 / --:--
Daniel KrügerGermankugel-3.5
0:00 / --:--
James WhitfieldEnglishkugel-3.5
0:00 / --:--
Julia ZieglerGermankugel-3.5
0:00 / --:--
Noah TremblayEnglishkugel-3.5

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.

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

Paginate Voices

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

Get Voice Details

Python
voice = client.voices.get(voice_id=1071)
print(f"Voice: {voice.name}")
print(f"Description: {voice.description}")
print(f"Sample URL: {voice.sample_url}")

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
audio = client.tts.generate(
    text="Hello with a specific voice!",
    model_id="kugel-3.5",
    voice_id=1071,
)

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

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

Voice Properties

Each voice includes the following information:

PropertyTypeDescription
idintUnique voice ID
voice_idintSame value as id for backward compatibility
handlestring | nullStable string identifier, when assigned; usable as voice_id on the raw API
public_idstring | nullPublic identifier, when assigned
namestringHuman-readable name
descriptionstring | nullVoice description
categorystringVoice catalog category
sexstring | nullmale, female, or neutral
agestring | nullVoice age label
qualitystringVoice quality label
supported_languageslistBCP-47 language tags (de-DE, en-GB)
sample_urlstring | nullSample audio URL
avatar_urlstring | nullVoice avatar URL

Next Steps