Skip to content
KugelAudioDocs

Generate Speech

Guide to generating speech from text with KugelAudio: basic and async generation, common parameters, browser playback and pre-connecting for lower latency.

On this page

Generate complete audio from text. This is the simplest way to get started: provide text and receive audio back.

Basic Generation

Python
from kugelaudio import KugelAudio

client = KugelAudio(api_key="your_api_key")

audio = client.tts.generate(
    text="Hello, this is a test of the KugelAudio text-to-speech system.",
    model_id="kugel-3.5",
    voice_id=1071,
)

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

# Or get WAV bytes
wav_bytes = audio.to_wav_bytes()

Generation Parameters

The parameters you'll touch most often (Python/REST snake_case; JavaScript uses camelCase):

  • text (required) and model_id: kugel-3.5 (the default) or kugel-3 (Models)
  • voice_id: the voice to speak with (Using voices)
  • cfg_scale: expressiveness (see the guide below)
  • temperature: sampling randomness (0 to 1); omit it to use the model default
  • normalize + language: text normalization. Always set the language when you know it; otherwise each sentence's language is recognized from its words, falling back to the voice's primary language
  • speed: playback rate (see Speed control below)
  • word_timestamps: word-level timestamps. SDK and WebSocket only; POST /v1/tts/generate rejects it with 400

The Generate Speech API reference is the canonical parameter table: every field with type, default, range, and error behavior, including output_format, project_id, and dictionary_ids.

CFG Scale Guide

The cfg_scale parameter controls how closely the model follows the voice characteristics. Accepted range: 1.2–2.5 (inclusive). Values outside this range are clamped into it.

RangeStyleBest For
1.2-1.5Relaxed, naturalConversational AI, long-form narration
2.0Balanced (default)General purpose
2.5ExpressiveStorytelling, emphasis-heavy content

Speed Control

speed changes the playback rate of the whole request with pitch-preserving time-stretching. The range is 0.8 to 1.2 (default 1.0); values outside it are rejected (400 on REST). To change the rate for part of a request, wrap that text in <prosody rate="...">. Examples and rules: Speed and per-span speed.

For pauses, codes, and pronunciation fixes, see the Prompting guide: <break> tags, <spell> tags, and the unsupported-tags table.

Example with Common Options

Python
audio = client.tts.generate(
    text="Hello, this is a test of the KugelAudio text-to-speech system.",
    model_id="kugel-3.5",
    voice_id=1071,
    cfg_scale=2.0,
    max_new_tokens=2048,
    sample_rate=24000,
    normalize=True,
    language="en",
    word_timestamps=False,
    speed=1.0,
)

# Inspect the response
print(f"Duration: {audio.duration_seconds:.2f}s")
print(f"Samples: {audio.samples}")
print(f"Sample rate: {audio.sample_rate} Hz")
print(f"Generation time: {audio.generation_ms:.0f}ms")
print(f"RTF: {audio.rtf:.2f}")

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

# Get raw PCM bytes
pcm_data = audio.audio

# Get WAV bytes (with header)
wav_bytes = audio.to_wav_bytes()

Async Generation

Python
import asyncio

async def main():
    audio = await client.tts.generate_async(
        text="Async generation example.",
        model_id="kugel-3.5",
        voice_id=1071,
    )
    audio.save("async_output.wav")

asyncio.run(main())

Playing Audio in the Browser

The JavaScript SDK provides utility functions for audio playback:

TypeScript
import { KugelAudio, createWavBlob } from 'kugelaudio';

const client = new KugelAudio({ apiKey: 'your_api_key' });

const audio = await client.tts.generate({
  text: 'Hello, world!',
  modelId: 'kugel-3.5',
  voiceId: 1071,
});

// Create WAV blob for playback
const wavBlob = createWavBlob(audio.audio, audio.sampleRate);
const url = URL.createObjectURL(wavBlob);

// Play with Audio element
const audioElement = new Audio(url);
audioElement.play();

// Or with Web Audio API
const audioContext = new AudioContext();
const arrayBuffer = await wavBlob.arrayBuffer();
const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
const source = audioContext.createBufferSource();
source.buffer = audioBuffer;
source.connect(audioContext.destination);
source.start();

Pre-connecting for Low Latency

For latency-sensitive applications, open the WebSocket connection at application startup so the handshake is not part of your first request. The per-SDK calls are in Latency: Pre-connect at startup.

Word Timestamps

Per-word time alignments (for subtitles, karaoke, lip-sync, and barge-in) are available from the SDKs and the WebSocket endpoints, not from POST /v1/tts/generate. See Word timestamps.

Next Steps