Skip to content
KugelAudioDocs

Quickstart

Install the KugelAudio SDK for Python, TypeScript/JavaScript, Java, Rust, C++ or Dart and generate your first audio

KugelAudio ships official SDKs for Python, TypeScript/JavaScript, Java, Rust, C++ and Dart. Every page of this reference shows each language in its own tab; pick your language once and every code block follows it.

SDKRuntimeSource (MIT, issues and pull requests welcome)
Python: Pythonic interface with synchronous and asynchronous APIsPython 3.10 or newerKugelaudio/python-sdk
TypeScript/JavaScript: type-safe interface for Node.js and browsersNode.js 18 or newer, or a modern browserKugelaudio/js-sdk
Java: type-safe builder interfaceJava 17 or newerKugelaudio/java-sdk
Rust: async client on Tokio, streams as futures::StreamRust 1.89 or newerKugelaudio/rust-sdk
C++: C++17 library with blocking calls and callbacksA C++17 compiler, CMake 3.20 or newer, libcurlKugelaudio/cpp-sdk
Dart: one package for Dart and Flutter, including Flutter webDart 3.4 or newerKugelaudio/dart-sdk

Installation

Bash
pip install kugelaudio

Or with uv (recommended):

Bash
uv add kugelaudio

Generate your first audio

Create an API key at app.kugelaudio.com/settings/api-keys and keep it out of your code, for example in the KUGELAUDIO_API_KEY environment variable (see Authentication). Only Java's KugelAudio.fromEnv() reads KUGELAUDIO_API_KEY for you; the other SDKs do not read the environment on their own, so pass the key explicitly.

import os

from kugelaudio import KugelAudio

# Initialize the client
client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])

# Generate speech
audio = client.tts.generate(
    text="Hello, world!",
    model_id="kugel-3.5",
    voice_id=1071,
)

# Save to file
audio.save("output.wav")

In a browser, the TypeScript SDK plays the audio instead of saving it: see Playing audio in the browser.

Pre-connecting for low latency

For latency-sensitive applications, pre-establish the WebSocket connection at startup to keep the handshake out of your first TTS request. Without pre-connecting, the first TTS request includes the WebSocket connection setup; later requests reuse the connection. See Latency for typical numbers.

In the examples below, play_audio / playAudio stands for your own playback function; the SDKs do not ship one.

Async applications (recommended):

Python
import asyncio
import os

from kugelaudio import AudioChunk, KugelAudio

async def main():
    # Create a pre-connected client (handshake happens here)
    client = await KugelAudio.create(api_key=os.environ["KUGELAUDIO_API_KEY"])

    # First request is now fast: no handshake on the hot path
    async for item in client.tts.stream_async("Hello, world!", voice_id=1071):
        if isinstance(item, AudioChunk):
            play_audio(item.audio)

    await client.aclose()

asyncio.run(main())

Sync applications. For synchronous code that needs connection reuse, keep a streaming session open across sends:

Python
import os

from kugelaudio import KugelAudio

client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])
with client.tts.streaming_session_sync(voice_id=1071) as session:
    for chunk in session.send("Hello, world!"):
        play_audio(chunk.audio)
    for chunk in session.flush():
        play_audio(chunk.audio)

Complete example

List the models and voices, generate audio and report its timing:

import os

from kugelaudio import KugelAudio

# Initialize client
client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])

# List available models
print("Available Models:")
for model in client.models.list():
    print(f"  - {model.id}: {model.name}")

# List available voices
print("\nAvailable Voices:")
result = client.voices.list(limit=5)
for voice in result.voices:
    print(f"  - {voice.id}: {voice.name}")

# Generate audio
print("\nGenerating audio...")
audio = client.tts.generate(
    text="Welcome to KugelAudio. This is an example of high-quality text-to-speech synthesis.",
    model_id="kugel-3.5",
    voice_id=1071,
)

print(f"Generated {audio.duration_seconds:.2f}s of audio in {audio.generation_ms:.0f}ms")
print(f"Real-time factor: {audio.rtf:.2f}x")

# Save to file
audio.save("example.wav")
print("Saved to example.wav")

# Close client
client.close()

Browser support

Not applicable: the Python SDK runs on your server.

Local turn detection (optional)

The Python SDK also ships an optional, local end-of-turn detector for voice agents. It runs on your machine, needs Python 3.11 or newer, and pulls in PyTorch, Transformers and ONNX Runtime:

Bash
pip install "kugelaudio[turn-detection]"
hf auth login  # the model bundle is downloaded from Hugging Face

Load the detector once per process and create one session per conversation. Supported languages are de, en, es, it and nl. pcm_chunk stands for 16 kHz mono PCM16 bytes of the user's audio:

Python
from kugelaudio.turn import TurnDetector, TurnMessage

detector = TurnDetector.from_pretrained()
turn = detector.create_session("en")

# Optional: prior dialogue, separate from the current user transcript
turn.update_history([
    TurnMessage("user", "I'd like to book a trip."),
    TurnMessage("assistant", "Where would you like to go?"),
])

# Feed the current user's audio and interim transcript continuously
turn.push_pcm16(pcm_chunk, sample_rate=16_000)
turn.update_transcript("To Berlin, and then")

# Call with the current silence duration whenever your VAD reports silence
decision = turn.observe_silence(duration_ms=200)
if decision.end_turn:
    turn.reset_turn()  # start the assistant response, then reset

History requires a bundle trained for multiple context messages; single-message bundles reject a nonempty history. Supply only messages already known at scoring time and assistant text that was actually spoken. update_history() replaces the history, reset_turn() keeps it, and reset_conversation() clears it.

Next steps