> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Generate Speech
> One-shot speech generation, generation parameters, models, and word timestamps
## Basic Generation
Generate complete audio and receive it all at once:
```python theme={null}
audio = client.tts.generate(
text="Hello, this is a test of the KugelAudio text-to-speech system.",
model_id="kugel-3", # Canonical production model (see /models)
voice_id=1071, # Required for successful synthesis
cfg_scale=2.0, # Guidance scale (1.2-2.5)
temperature=None, # Sampling variance 0.0-1.0; None = server default
max_new_tokens=2048, # Maximum tokens to generate
sample_rate=24000, # Output sample rate
normalize=True, # Enable text normalization (default)
language="en", # Language for normalization (see /sdks/python/normalization)
word_timestamps=False, # Request word-level timestamps (default: False)
speed=1.0, # Playback speed 0.8-1.2 (pitch-preserving WSOLA)
)
# Audio properties
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}") # Real-time factor
# 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()
# Get float32 samples in [-1.0, 1.0]
samples = audio.to_float32()
# Save raw PCM instead of WAV
audio.save("output.pcm", format="raw")
```
`to_float32()`, `to_wav_bytes()`, and `save(..., format="wav")` expect PCM16
output. For `ulaw_8000` or `alaw_8000`, use `audio.audio` as raw G.711 bytes.
### Generation parameters
These parameters are accepted by `generate()`, `generate_async()`, `stream()`,
and `stream_async()`.
| Parameter | Type | Default | Description |
| ----------------- | ------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text` | `str` | required | Text to synthesize. Supports [``](/prompting/breaks) and [``](/prompting/spell) tags. |
| `model_id` | `str` | `"kugel-3"` | TTS model. See [Models](/models). |
| `voice_id` | `int \| None` | `None` in the SDK signature | Voice to use. Required for successful synthesis; omission fails with `MISSING_VOICE_ID`. |
| `cfg_scale` | `float` | `2.0` | Classifier-free guidance scale (1.2–2.5; values outside are clamped). Higher tracks the reference voice more tightly. |
| `temperature` | `float \| None` | `None` | Sampling variance in \[0.0, 1.0]. `None` leaves the value unset so the server chooses its default. `0.0` is most stable (near-greedy); lower values give more consistent reads across regenerations. |
| `max_new_tokens` | `int` | `2048` | Maximum tokens to generate. |
| `sample_rate` | `int` | `24000` | Output sample rate in Hz. |
| `output_format` | `str \| None` | `None` | Combined codec + rate token. Supported native tokens: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `ulaw_8000`, `alaw_8000`. When set it must not contradict `sample_rate`. |
| `normalize` | `bool` | `True` | Enable text normalization (numbers, dates, etc. → spoken words). |
| `language` | `str \| None` | `None` | ISO 639-1 code for normalization. Always set when known to skip language auto-detection — see [Latency](/latency). |
| `word_timestamps` | `bool` | `False` | Request per-word time alignments. |
| `speed` | `float` | `1.0` | Playback speed multiplier (0.8 = slower, 1.2 = faster). Uses pitch-preserving WSOLA time-stretching; `` spans in the text override it per span — see [Speed](/prompting/speed#per-span-speed-with-prosody-rate). |
| `dictionary_ids` | `list[int] \| None` | `None` | Serialized dictionary selection. The API requires `project_id` with a non-empty list, but this SDK request does not expose `project_id`; `None` and `[]` therefore load no dictionary, while a non-empty list is rejected. Use the raw API or JavaScript one-shot client for dictionary-backed synthesis. |
## Async Generation
```python theme={null}
import asyncio
async def main():
audio = await client.tts.generate_async(
text="Async generation example.",
model_id="kugel-3",
voice_id=1071,
)
audio.save("async_output.wav")
asyncio.run(main())
```
## Word Timestamps with Generate
Request word-level time alignments alongside audio when using `generate()`:
```python theme={null}
audio = client.tts.generate(
text="Hello, how are you today?",
model_id="kugel-3",
voice_id=1071,
word_timestamps=True,
)
# Access word timestamps from the response
for ts in audio.word_timestamps:
print(f"{ts.word}: {ts.start_ms}ms - {ts.end_ms}ms (score: {ts.score:.2f})")
# Example output:
# Hello: 0ms - 320ms (score: 1.00)
# how: 350ms - 480ms (score: 1.00)
# are: 500ms - 580ms (score: 1.00)
# you: 600ms - 720ms (score: 1.00)
# today: 750ms - 1100ms (score: 1.00)
```
Word timestamps are also available with async generation:
```python theme={null}
audio = await client.tts.generate_async(
text="Hello, world!",
model_id="kugel-3",
voice_id=1071,
word_timestamps=True,
)
for ts in audio.word_timestamps:
print(f"{ts.word}: {ts.start_ms}-{ts.end_ms}ms")
```
## Models
### List Available Models
```python theme={null}
models = client.models.list()
for model in models:
print(f"{model.id}: {model.name}")
print(f" Description: {model.description}")
print(f" Max Input: {model.max_input_length} characters")
print(f" Sample Rate: {model.sample_rate} Hz")
```
## Next steps
* [Streaming](/sdks/python/streaming) — receive audio chunks as they are generated
* [Text Normalization](/sdks/python/normalization) — languages and spell tags
* [Types & Errors](/sdks/python/types) — `AudioResponse`, `WordTimestamp`, and exceptions