Skip to content
KugelAudioDocs

Quick Start

Get started with the KugelAudio text-to-speech API: hear a first clip with one cURL command, claim your free credit, install an SDK, generate speech and stream audio.

On this page

Hear your first clip

Three steps from an API key to German speech playing on your machine. You need cURL and FFmpeg (brew install ffmpeg, sudo apt install ffmpeg or winget install ffmpeg).

  1. Create an API key

    Sign up and create a key in the dashboard. New accounts start with free credit. Put the key in your shell:

    Bash
    export KUGELAUDIO_API_KEY="your_api_key"
  2. Generate a WAV file

    This sends a German sentence to kugel-3.5 with the public voice 979 (Sara Wagner). The API streams back raw PCM (Audio formats), and FFmpeg writes it to hello.wav:

    Bash
    curl -sS --fail -X POST https://api.kugelaudio.com/v1/tts/generate \
      -H "Authorization: Bearer $KUGELAUDIO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"text": "Hallo! Das ist mein erster Satz mit KugelAudio.", "model_id": "kugel-3.5", "voice_id": 979, "language": "de"}' \
      | ffmpeg -y -loglevel error -f s16le -ar 24000 -ac 1 -i - hello.wav

    Run it in bash or zsh; on Windows, use Git Bash. If curl reports an HTTP status such as 401 (missing or wrong key), look it up in Errors.

  3. Play it
    Bash
    afplay hello.wav   # macOS
    aplay hello.wav    # Linux
    start hello.wav    # Windows

    To generate from code instead, install an SDK below.

Free credit to start

Every new account gets €5 of Text to Speech credit once: at least 70 minutes of audio with any model, no credit card, and the credit does not expire. The rates for each model are on the pricing page.

Prerequisites

Before you begin, make sure you have:

Installation

Install the Python SDK using pip or uv:

Bash
pip install kugelaudio

Or with uv (recommended):

Bash
uv add kugelaudio

Basic Usage

Initialize the Client

Python
from kugelaudio import KugelAudio

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

Generate Speech

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

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

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

Stream Audio

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

Python
# Synchronous streaming
for chunk in client.tts.stream(
    text="Hello, this is streaming audio.",
    model_id="kugel-3.5",
    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:

Python
import asyncio

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

asyncio.run(stream_audio())

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
german = client.voices.list(language="de", limit=100)
for voice in german.voices:
    print(f"{voice.id}: {voice.name}")

Next Steps

Your SDK