Quick Start

Prerequisites

Before you begin, make sure you have:

An API key: create one in the dashboard. Plans and credits are on the pricing page.
Python 3.10+, Node.js 18+, Java 17+, or cURL (plus FFmpeg to play the raw audio cURL returns)

Installation

Python
TypeScript/JavaScript
Java
cURL

Install the Python SDK using pip or uv:

pip install kugelaudio

Or with uv (recommended):

uv add kugelaudio

Install the TypeScript/JavaScript SDK using your preferred package manager:

npm install kugelaudio

Or with yarn/pnpm:

yarn add kugelaudio
# or
pnpm add kugelaudio

Add the dependency to your pom.xml (requires Java 17+):

<dependency>
  <groupId>com.kugelaudio</groupId>
  <artifactId>kugelaudio</artifactId>
  <version>3.0.0</version>
</dependency>

Or with Gradle:

implementation 'com.kugelaudio:kugelaudio:3.0.0'

cURL comes pre-installed on macOS, Linux, and Windows 10+. No installation needed.Set your API key as an environment variable:

export KUGELAUDIO_API_KEY="your_api_key"

Basic Usage

Initialize the Client

Connect once at startup. Call connect() once (JavaScript, Java) or use await KugelAudio.create(...) (async Python) so the first request does not pay the connection handshake. See Latency.

Python
JavaScript
Java
cURL

from kugelaudio import KugelAudio

# Initialize for synchronous generate() / stream() calls
client = KugelAudio(api_key="your_api_key")

import { KugelAudio } from 'kugelaudio';

// Initialize with your API key
const client = new KugelAudio({ apiKey: 'your_api_key' });

// Pre-connect at startup (handshake happens here)
await client.connect();

// Confirm connection is ready
console.log(`Connected: ${client.isConnected()}`);

// The first request no longer pays the handshake

import com.kugelaudio.sdk.KugelAudio;
import com.kugelaudio.sdk.KugelAudioOptions;

KugelAudio client = new KugelAudio(
    KugelAudioOptions.builder("your_api_key").build()
);

// Pre-connect at startup (handshake happens here)
client.connect();

// Confirm connection is ready
System.out.println("Connected: " + client.isConnected());

// The first request no longer pays the handshake

No client initialization needed. Pass the API key in the Authorization header; this request fails if the key is missing or invalid:

curl --fail-with-body "https://api.kugelaudio.com/v1/voices?limit=1" \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

Generate Speech

Examples below use kugel-3, the current model. See Models for details.

Python
JavaScript
Java
cURL

# Generate speech
audio = client.tts.generate(
    text="Welcome to KugelAudio! This is high-quality text-to-speech.",
    model_id="kugel-3",
    voice_id=1071,
)

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

# Or get the raw bytes
wav_bytes = audio.to_wav_bytes()

// Generate speech
const audio = await client.tts.generate({
  text: 'Welcome to KugelAudio! This is high-quality text-to-speech.',
  modelId: 'kugel-3',
  voiceId: 1071,
});

// audio.audio is an ArrayBuffer with PCM16 data
console.log(`Duration: ${audio.durationMs}ms`);

import com.kugelaudio.sdk.GenerateRequest;
import com.kugelaudio.sdk.AudioResponse;

AudioResponse audio = client.tts().generate(
    GenerateRequest.builder("Welcome to KugelAudio! This is high-quality text-to-speech.")
        .modelId("kugel-3")
        .voiceId(1071)
        .language("en")
        .build()
);

// Save to file
audio.saveWav(java.nio.file.Path.of("output.wav"));

curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Welcome to KugelAudio! This is high-quality text-to-speech.",
    "model_id": "kugel-3",
    "voice_id": 1071
  }' \
  --output output.pcm

# Convert to WAV for playback
ffmpeg -f s16le -ar 24000 -ac 1 -i output.pcm output.wav

Stream Audio

For lower latency, stream audio chunks as they’re generated:

Python
JavaScript
Java
cURL

# Synchronous streaming
for chunk in client.tts.stream(
    text="Hello, this is streaming audio.",
    model_id="kugel-3",
    voice_id=1071,
):
    if hasattr(chunk, 'audio'):
        # Process audio chunk immediately
        print(f"Chunk {chunk.index}: {len(chunk.audio)} bytes")
        # play_audio(chunk.audio)

For async applications:

import asyncio

async def stream_audio():
    async for chunk in client.tts.stream_async(
        text="Async streaming example.",
        model_id="kugel-3",
        voice_id=1071,
    ):
        if hasattr(chunk, 'audio'):
            # Process chunk
            pass

asyncio.run(stream_audio())

await client.tts.stream(
  {
    text: 'Hello, this is streaming audio.',
    modelId: 'kugel-3',
    voiceId: 1071,
  },
  {
    onChunk: (chunk) => {
      console.log(`Chunk ${chunk.index}: ${chunk.samples} samples`);
      // Play or process the audio chunk
    },
    onFinal: (stats) => {
      console.log(`Total duration: ${stats.durationMs}ms`);
      console.log(`Generation time: ${stats.generationMs}ms`);
    },
  }
);

import com.kugelaudio.sdk.StreamCallbacks;
import com.kugelaudio.sdk.AudioChunk;

client.tts().stream(
    GenerateRequest.builder("Hello, this is streaming audio.")
        .modelId("kugel-3")
        .voiceId(1071)
        .language("en")
        .build(),
    new StreamCallbacks() {
        @Override
        public void onChunk(AudioChunk chunk) {
            System.out.printf("Chunk %d: %d bytes%n",
                chunk.getIndex(), chunk.getAudio().length);
            // playAudio(chunk.getAudio());
        }
    }
);

The REST endpoint streams raw PCM bytes. Pipe them to ffplay for real-time playback:

curl -X POST https://api.kugelaudio.com/v1/tts/generate \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is streaming audio.",
    "model_id": "kugel-3",
    "voice_id": 1071
  }' \
  --no-buffer | ffplay -f s16le -ar 24000 -ac 1 -nodisp -autoexit -

For advanced streaming (WebSocket-based, token-by-token from LLMs), use the Python, JavaScript, or Java SDK or the raw WebSocket API.

Working with Voices

The examples above use voice 1071. To pick another, list the voices your key can use. The listing returns all voices, one page at a time; pass language to get only the voices that speak it: de matches every German accent (de-DE, de-AT), de-AT only Austrian German. See Voices for pagination, voice details, and cloning.

Python
JavaScript
Java
cURL

german = client.voices.list(language="de", limit=100)
for voice in german.voices:
    print(f"{voice.id}: {voice.name}")

const german = await client.voices.list({ language: 'de', limit: 100 });
for (const voice of german.voices) {
  console.log(`${voice.id}: ${voice.name}`);
}

import com.kugelaudio.sdk.Voice;

for (Voice voice : client.voices().list("de", null, 100, 0).getVoices()) {
    System.out.printf("%d: %s%n", voice.getId(), voice.getName());
}

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

Pick your voice deliberately. Voices differ in baseline energy, age, and warmth. Listen to several with representative text before choosing one. Building an LLM-driven voice agent? See Voice Agent Prompting.

Next Steps

Generate Speech

All generation options and parameters

Streaming

Real-time audio streaming techniques

Using Voices

Browse voices, paginate, and clone

Text Processing

Normalization and spell tags

Your SDK

Python

Python SDK reference

TypeScript/JavaScript

TypeScript/JavaScript SDK reference

Java

Java SDK reference

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Prerequisites

Installation

Basic Usage

Initialize the Client

Generate Speech

Stream Audio

Working with Voices

Next Steps

Generate Speech

Streaming

Using Voices

Text Processing

Your SDK

Python

TypeScript/JavaScript

Java

​Prerequisites

​Installation

​Basic Usage

​Initialize the Client

​Generate Speech

​Stream Audio

​Working with Voices

​Next Steps

Generate Speech

Streaming

Using Voices

Text Processing

​Your SDK

Python

TypeScript/JavaScript

Java

Prerequisites

Installation

Basic Usage

Initialize the Client

Generate Speech

Stream Audio

Working with Voices

Next Steps

Your SDK