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).
- 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:
Bashexport KUGELAUDIO_API_KEY="your_api_key" - Generate a WAV file
This sends a German sentence to
kugel-3.5with the public voice979(Sara Wagner). The API streams back raw PCM (Audio formats), and FFmpeg writes it tohello.wav:Bashcurl -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.wavRun 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. - Play itBash
afplay hello.wav # macOS aplay hello.wav # Linux start hello.wav # WindowsTo 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:
- An API key: sign up and create one in the dashboard.
- Python 3.10+, Node.js 18+, Java 17+, or cURL (plus FFmpeg to play the raw audio cURL returns)
Installation
Install the Python SDK using pip or uv:
pip install kugelaudioOr with uv (recommended):
uv add kugelaudioInstall the TypeScript/JavaScript SDK using your preferred package manager:
npm install kugelaudioOr with yarn/pnpm:
yarn add kugelaudio
# or
pnpm add kugelaudioAdd 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
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 handshakeimport 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 handshakeNo 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
# 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()// Generate speech
const audio = await client.tts.generate({
text: 'Welcome to KugelAudio! This is high-quality text-to-speech.',
modelId: 'kugel-3.5',
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.5")
.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.5",
"voice_id": 1071
}' \
--output output.pcm
# Convert to WAV for playback
ffmpeg -f s16le -ar 24000 -ac 1 -i output.pcm output.wavStream Audio
For lower latency, stream audio chunks as they're generated:
# 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:
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())await client.tts.stream(
{
text: 'Hello, this is streaming audio.',
modelId: 'kugel-3.5',
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.5")
.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.5",
"voice_id": 1071
}' \
--no-buffer | ffplay -f s16le -ar 24000 -ac 1 -nodisp -autoexit -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.
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"