Quick Start

Prerequisites

Before you begin, make sure you have:

An API key from kugelaudio.com
Python 3.9+, Node.js 18+, Java 17+, or cURL

Installation

Python
JavaScript/TypeScript
Java
cURL

Install the Python SDK using pip or uv:

pip install kugelaudio

Or with uv (recommended):

uv add kugelaudio

Install the 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>0.1.0</version>
</dependency>

Or with Gradle:

implementation 'com.kugelaudio:kugelaudio:0.1.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

Python
JavaScript
Java
cURL

from kugelaudio import KugelAudio

# Initialize with your API key
client = KugelAudio(api_key="your_api_key")

import { KugelAudio } from 'kugelaudio';

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

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

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

No client initialization needed — just pass the API key in the Authorization header:

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

Generate Speech

Python
JavaScript
Java
cURL

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

# 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-1-turbo',
});

// 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-1-turbo")
        .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-1-turbo"
  }' \
  --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-1-turbo",
):
    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-1-turbo",
    ):
        if hasattr(chunk, 'audio'):
            # Process chunk
            pass

asyncio.run(stream_audio())

await client.tts.stream(
  {
    text: 'Hello, this is streaming audio.',
    modelId: 'kugel-1-turbo',
  },
  {
    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-1-turbo")
        .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 directly 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-1-turbo"
  }' \
  --no-buffer | ffplay -f s16le -ar 24000 -ac 1 -nodisp -

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

List Available Voices

Python
JavaScript
Java
cURL

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

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

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

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

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

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

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("  Languages: %s%n",
        String.join(", ", voice.getSupportedLanguages()));
}

// Filter by language
List<Voice> germanVoices = client.voices().list("de");

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

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

Use a Specific Voice

Python
JavaScript
Java
cURL

audio = client.tts.generate(
    text="Hello with a specific voice!",
    model_id="kugel-1-turbo",
    voice_id=123,  # Use a specific voice ID
)

const audio = await client.tts.generate({
  text: 'Hello with a specific voice!',
  modelId: 'kugel-1-turbo',
  voiceId: 123,  // Use a specific voice ID
});

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

Next Steps

Generate Speech

All generation options and parameters

Streaming

Real-time audio streaming techniques

Using Voices

Browse and filter available voices

Text Processing

Normalization and spell tags

Getting Started

Speech Generation

Voices

Integrations

Self-Hosted

SDK Reference

Prerequisites

Installation

Basic Usage

Initialize the Client

Generate Speech

Stream Audio

Working with Voices

List Available Voices

Use a Specific Voice

Next Steps

Generate Speech

Streaming

Using Voices

Text Processing

Getting Started

Speech Generation

Voices

Integrations

Self-Hosted

SDK Reference

​Prerequisites

​Installation

​Basic Usage

​Initialize the Client

​Generate Speech

​Stream Audio

​Working with Voices

​List Available Voices

​Use a Specific Voice

​Next Steps

Generate Speech

Streaming

Using Voices

Text Processing

Prerequisites

Installation

Basic Usage

Initialize the Client

Generate Speech

Stream Audio

Working with Voices

List Available Voices

Use a Specific Voice

Next Steps