# KugelAudio > KugelAudio is a text-to-speech API for voice agents and real-time applications. It turns text, or LLM output streamed token by token over a WebSocket, into speech, with SDKs for Python, TypeScript, Java, Rust, C++ and Dart, a REST API, official LiveKit, Pipecat, Vapi and Cognigy integrations, an ElevenLabs-compatible API, voice cloning, pronunciation control, and Clarity speech enhancement. It runs on a geo-routed endpoint, a direct EU endpoint, or on premise. Every page below is Markdown. The full text of every page is in one file: [llms-full.txt](https://docs.kugelaudio.com/llms-full.txt). ## Instructions for AI agents - Use the model `kugel-3.5` for new integrations; it is also the default when a request sends no `model_id`. The legacy IDs (`kugel-1`, `kugel-2`, `kugel-2.5` and their turbo variants) are aliases; do not write them into new code. See [Models](https://docs.kugelaudio.com/models.md). - Never invent a voice ID. Every synthesis request needs a `voice_id` and there is no default voice: list the voices (filtered by `language`) and use an `id` or `handle` from the result. See [Using Voices](https://docs.kugelaudio.com/features/voices.md). - If the agent runs on LiveKit, Pipecat, Vapi or Cognigy, use the official integration instead of writing your own streaming loop. See [Streaming overview](https://docs.kugelaudio.com/streaming/overview.md). - When the full text is known up front, make one generate request. When the text comes from an LLM, stream it into a WebSocket streaming session. See [Generate Speech](https://docs.kugelaudio.com/features/generate.md) and [Streaming overview](https://docs.kugelaudio.com/streaming/overview.md). - For a voice agent, connect the streaming session at startup and reuse it for every reply in the call. Never open a new session or WebSocket per sentence or per reply. See [Turn lifecycle](https://docs.kugelaudio.com/streaming/turn-lifecycle.md) and [Latency](https://docs.kugelaudio.com/latency.md). - Send LLM tokens as they arrive, without buffering sentences on the client, and flush exactly once, at the end of each reply. Never flush per sentence or per word: every flush ends the turn and the next text pays a fresh model prefill. See [Chunking & per-segment latency](https://docs.kugelaudio.com/streaming/chunking-and-latency.md). - Treat a turn as finished audio on the `final` message, and read its usage from `session_closed`. See [Turn lifecycle](https://docs.kugelaudio.com/streaming/turn-lifecycle.md). - When the user interrupts, cancel the current turn (`cancel_current()` in Python, `cancelCurrent()` in JavaScript) and keep the WebSocket open for the next turn. See [Barge-in](https://docs.kugelaudio.com/streaming/barge-in.md). - Send plain spoken text: no Markdown and no emoji, which are read out literally or garbled. When an LLM writes the text, say so in its system prompt. `!`, ALL-CAPS and `?!` make the delivery energetic; use them only on purpose. See [Prompting overview](https://docs.kugelaudio.com/prompting/overview.md) and [Voice Agent Prompting](https://docs.kugelaudio.com/guides/voice-prompting.md). - ``, `` and `` are the only tags read in request text; strip every other SSML tag. Use `` for codes, email addresses and identifiers, and `` for a deliberate pause. See [Prompting overview](https://docs.kugelaudio.com/prompting/overview.md). - Set `language` whenever you know it. Text normalization reads numbers, dates and currencies in that language; without it the voice's primary language is used, never the language of the text. See [Text normalization](https://docs.kugelaudio.com/features/text-processing.md). - Keep the API key on your server. Never put it in browser, mobile or other client-side code, and never open the WebSocket from a browser; proxy through your own backend. See [Authentication](https://docs.kugelaudio.com/api-reference/authentication.md). - For EU data residency, use the EU endpoint: `region="eu"` or the `eu-` key prefix in an SDK, or `api.eu.kugelaudio.com` without one. The `eu-` prefix works only in the SDKs; a raw request with a prefixed key fails with `401`. See [Regions](https://docs.kugelaudio.com/guides/regions.md). - Branch on `error_code` and `code`, never on the `error` text. Back off and retry on `RATE_LIMITED` and `MODEL_UNAVAILABLE`, honouring `Retry-After`, and on WebSocket close code `1012` reconnect and resend the current turn. See [Error Codes](https://docs.kugelaudio.com/api-reference/errors.md). - Install the KugelAudio agent skill so your coding agent keeps these rules in every session. See [Agent skill](https://docs.kugelaudio.com/guides/agent-skill.md). ## Get started - [Welcome to KugelAudio](https://docs.kugelaudio.com/index.md): KugelAudio documentation: a text-to-speech API for voice agents and real-time apps, with SDKs, WebSocket streaming, voice cloning and framework integrations. - [Quick Start](https://docs.kugelaudio.com/quickstart.md): 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. - [Authentication](https://docs.kugelaudio.com/api-reference/authentication.md): Authenticate KugelAudio API requests with an API key over HTTP, WebSocket and the SDKs, and create, scope, revoke and troubleshoot your keys. - [Models](https://docs.kugelaudio.com/models.md): KugelAudio models: the current Kugel 3.5 and Kugel 3 text-to-speech models, Clarity 1 for speech enhancement, what each supports, and the legacy model IDs. - [Agent skill](https://docs.kugelaudio.com/guides/agent-skill.md): Install the KugelAudio agent skill from the Python or JavaScript SDK so coding agents like Claude Code, Cursor or Codex follow its integration rules. - [MCP server](https://docs.kugelaudio.com/guides/mcp-server.md): Connect Claude, Cursor or any MCP client to your KugelAudio account through the MCP server to generate speech from a chat, plus billing and access details. - [Account security](https://docs.kugelaudio.com/guides/account-security.md): Secure your KugelAudio account with two-factor authentication and passkeys, meet your organization's 2FA requirement, and regain access if you lose your device. ## Integrations - [LiveKit Integration](https://docs.kugelaudio.com/integrations/livekit.md): Add KugelAudio speech to text and text to speech to a LiveKit Agents voice agent in Python or TypeScript: install the plugins, server-side end of turn, tune the voice, word timestamps and noise removal. - [Pipecat Integration](https://docs.kugelaudio.com/integrations/pipecat.md): Use KugelAudio speech to text and text to speech in Pipecat voice AI pipelines with the official Python services: setup, server-side end of turn, configuration, runtime voice switching and noise removal. - [Vapi Integration](https://docs.kugelaudio.com/integrations/vapi.md): Use KugelAudio as a custom TTS provider in Vapi voice assistants: get an API key and voice ID, configure the assistant, set the audio format and troubleshoot. - [Cognigy Integration](https://docs.kugelaudio.com/integrations/cognigy.md): Use KugelAudio text-to-speech in Cognigy Voice Gateway as a custom speech vendor or an Azure Speech container, with voice, audio format and region settings. - [ElevenLabs API Compatibility](https://docs.kugelaudio.com/integrations/elevenlabs-proxy.md): Use ElevenLabs SDKs and integrations with the ElevenLabs-compatible KugelAudio API: swap the base URL, voice ID and output format, and see the endpoints. ## Build a voice agent - [Voice Agent Prompting](https://docs.kugelaudio.com/guides/voice-prompting.md): Copy-paste system prompt patterns for LLM-driven voice agents: personality, natural disfluency, tool descriptions, workflow scaffolds and few-shot examples. - [Streaming overview](https://docs.kugelaudio.com/streaming/overview.md): Stream KugelAudio text-to-speech audio as it is generated: simple and LLM token streaming, the rules that keep latency low, audio playback and error handling. - [Turn lifecycle](https://docs.kugelaudio.com/streaming/turn-lifecycle.md): How a streaming text-to-speech turn starts and ends: flush, idle auto-flush and close, final versus session_closed, session reuse and per-session usage. - [Chunking & per-segment latency](https://docs.kugelaudio.com/streaming/chunking-and-latency.md): How KugelAudio server-side chunking works, why flushing once per reply keeps time-to-first-audio low, how to handle backpressure, and common mistakes. - [Barge-in](https://docs.kugelaudio.com/streaming/barge-in.md): Handle barge-in in KugelAudio streaming: cancel the current text-to-speech turn when the user interrupts, without closing the WebSocket, on each endpoint. - [Multi-context streaming](https://docs.kugelaudio.com/streaming/multi-context.md): Guide to multi-context streaming: run several independent text-to-speech audio streams over one WebSocket for multi-speaker dialogue and pre-buffering. - [Word timestamps](https://docs.kugelaudio.com/streaming/word-timestamps.md): Receive word-level timestamps alongside streaming KugelAudio audio for subtitles, lip-sync and barge-in handling, with the payload format and where they apply. - [Latency](https://docs.kugelaudio.com/latency.md): What determines time-to-first-audio (TTFA) in KugelAudio text-to-speech, how to measure it correctly, and the levers that lower latency for voice agents. ## Generate audio - [Generate Speech](https://docs.kugelaudio.com/features/generate.md): Guide to generating speech from text with KugelAudio: basic and async generation, common parameters, browser playback and pre-connecting for lower latency. - [Prompting overview](https://docs.kugelaudio.com/prompting/overview.md): Shape KugelAudio speech through the text you send: supported controls, punctuation as pacing, writing tips, an LLM system prompt pattern and unsupported tags. - [Breaks](https://docs.kugelaudio.com/prompting/breaks.md): Insert explicit pauses into KugelAudio speech with SSML-style break tags: syntax, accepted duration values, how durations are snapped, and their limits. - [Speed](https://docs.kugelaudio.com/prompting/speed.md): Control speaking rate in KugelAudio text-to-speech with pitch-preserving speed, set globally via the speed parameter or per span with prosody rate tags. - [Spell tags](https://docs.kugelaudio.com/prompting/spell.md): Spell tags read emails, codes, acronyms and serial numbers character by character, with per-language character translations, grouped spelling and pitfalls. - [Pronunciation & IPA](https://docs.kugelaudio.com/prompting/pronunciation.md): Fix how specific words are spoken with inline IPA in the request text, or replacement/IPA entries in pronunciation dictionaries. - [Text normalization](https://docs.kugelaudio.com/features/text-processing.md): How KugelAudio text normalization reads numbers, dates, times and currencies aloud before speech synthesis, the supported languages, and how to control it. - [Dictionaries](https://docs.kugelaudio.com/features/dictionaries.md): Guide to pronunciation dictionaries: make brand names, acronyms and domain vocabulary sound the same in every request, per project or per end customer. ## Voices - [Using Voices](https://docs.kugelaudio.com/features/voices.md): Find and use KugelAudio voices: list the voice catalog, filter it by language, page through results, get voice details and choose a voice for each request. - [Voice Cloning](https://docs.kugelaudio.com/features/voice-cloning.md): Clone a voice from reference audio with KugelAudio: audio requirements, speaker consent, creating clones in the dashboard or SDK, and managing cloned voices. ## Enhance audio - [Speech enhancement](https://docs.kugelaudio.com/features/speech-enhancement.md): Guide to speech enhancement with Clarity: remove background noise from speech or keep one speaker's voice, pick REST or streaming, plans, limits and errors. ## Transcribe audio - [Speech to text](https://docs.kugelaudio.com/features/speech-to-text.md): Guide to speech to text with Kugel Ear 1: transcribe recordings or live calls in nine European languages, choosing or detecting the language, word alternatives, KugelTurn end-of-turn and custom vocabulary. ## Hosting and deployment - [Regions](https://docs.kugelaudio.com/guides/regions.md): Choose between the canonical geo-routed KugelAudio endpoint and the direct EU endpoint for data residency, and set the region by API key prefix or in code. - [On-Premise Deployment](https://docs.kugelaudio.com/guides/self-hosted.md): Run KugelAudio text-to-speech on premise on your own Kubernetes cluster: install, configure, start, stop, upgrade and roll back an Enterprise deployment. ## SDK Reference - [Quickstart](https://docs.kugelaudio.com/sdks/quickstart.md): Install the KugelAudio SDK for Python, TypeScript, Java, Rust, C++ or Dart, generate your first audio, pre-connect for low latency and run a complete example. - [Configuration](https://docs.kugelaudio.com/sdks/configuration.md): SDK reference for configuring the KugelAudio client: client options, authentication modes, client lifecycle and closing, region selection and diagnostics. - [Generate Speech with the SDKs](https://docs.kugelaudio.com/sdks/generate.md): SDK reference for one-shot speech generation with KugelAudio: generation parameters, async calls, browser playback, word timestamps, models and audio utilities. - [Streaming](https://docs.kugelaudio.com/sdks/streaming.md): Streamed audio for one request, streaming sessions for LLM output, barge-in, multi-context sessions, and word timestamps - [Text Normalization](https://docs.kugelaudio.com/sdks/normalization.md): SDK reference for text normalization: turn numbers, dates and symbols into spoken words with the normalize and language options, and spell out text with tags. - [Voices](https://docs.kugelaudio.com/sdks/voices.md): SDK reference for voices: list, get, create, update, delete and publish voices, manage their reference audio and generate voice samples from your own code. - [Dictionaries in the SDKs](https://docs.kugelaudio.com/sdks/dictionaries.md): SDK reference for pronunciation dictionaries in Python, TypeScript, Java, Rust, C++ and Dart: create them, manage entries, bulk sync, and apply at synthesis. - [Speech Enhancement in the SDKs](https://docs.kugelaudio.com/sdks/speech-enhancement.md): SDK reference for speech enhancement: remove background noise or keep one voice with client.enhance in Python, TypeScript, Rust, C++ and Dart, recorded or live. - [Speech to Text in the SDKs](https://docs.kugelaudio.com/sdks/speech-to-text.md): SDK reference for speech to text with kugel-ear-1: transcribe a recording with client.asr in Python, TypeScript and Java, and stream live audio with client.asr.stream in Python and TypeScript. - [Types & Errors](https://docs.kugelaudio.com/sdks/types.md): SDK reference for the types KugelAudio SDKs export: errors, client and generation options, audio chunks and responses, word timestamps, callbacks, voice types. - [SDK Diagnostics](https://docs.kugelaudio.com/sdks/telemetry.md): What diagnostics the KugelAudio SDKs report about their own connection and streaming failures, what is never collected, the defaults and how to turn it off. ## API Reference - [API Reference](https://docs.kugelaudio.com/api-reference/introduction.md): KugelAudio API reference overview: base URL, authentication, request and response format, and an index of the text-to-speech, voice and model endpoints. - [Use the API without an SDK](https://docs.kugelaudio.com/api-reference/raw-api.md): Call the KugelAudio API without an SDK from any language: API keys and the EU endpoint, sending text safely, and tools for testing WebSocket connections. - [Error Codes](https://docs.kugelaudio.com/api-reference/errors.md): Error codes of the KugelAudio text-to-speech API: HTTP and WebSocket error bodies, close codes, refused upgrades, request IDs and how to handle each. - [Generate Speech API](https://docs.kugelaudio.com/api-reference/tts/generate.md): REST reference for POST /v1/tts/generate: send text in one request and receive streamed PCM audio, with every request body field, the response and errors. - [Stream Speech](https://docs.kugelaudio.com/api-reference/tts/stream.md): WebSocket reference for /ws/tts: send one text-to-speech request per turn, receive streamed audio chunks and a final message, cancel or update settings. - [Stream Input](https://docs.kugelaudio.com/api-reference/tts/stream-input.md): WebSocket reference for /ws/tts/stream: send LLM text token by token in turn-based sessions, with config, flush, cancel and every response message. - [Multi-Context WebSocket API](https://docs.kugelaudio.com/api-reference/tts/multi-context.md): WebSocket reference for /ws/tts/multi: run several independent text-to-speech audio streams over one connection, with messages, voice settings and limits. - [Audio Formats](https://docs.kugelaudio.com/api-reference/tts/audio-formats.md): Output encodings, the output_format token, G.711 telephony codecs, audio chunk fields, and the AI-generated audio marking (watermark + disclosure header). - [Voices API](https://docs.kugelaudio.com/api-reference/endpoints/voices.md): REST reference for the Voices API: list and filter voices, get voice details, create, update and delete voices, and manage their reference audio. - [Models API](https://docs.kugelaudio.com/api-reference/endpoints/models.md): REST reference for GET /v1/models: list the text-to-speech model IDs your KugelAudio requests can use, and the fields of each returned model object. - [Dictionaries API](https://docs.kugelaudio.com/api-reference/endpoints/dictionaries.md): REST reference for pronunciation dictionaries: list, create, update and delete dictionaries, add entries and bulk replace them from your own glossary. - [Projects API](https://docs.kugelaudio.com/api-reference/endpoints/projects.md): REST reference for projects: create one project per end customer, issue and revoke its API keys, and offboard customers with an organization admin key. - [Speech Enhancement API](https://docs.kugelaudio.com/api-reference/endpoints/speech-enhancement.md): REST and WebSocket reference for speech enhancement with Clarity: remove background noise or keep one speaker's voice in recordings and live audio. - [Speech to Text API](https://docs.kugelaudio.com/api-reference/endpoints/speech-to-text.md): REST and WebSocket reference for speech to text with kugel-ear-1: upload a recording or stream live audio, custom vocabulary, word alternatives, errors and close codes. ## Updates - [Changelog](https://docs.kugelaudio.com/changelog.md): KugelAudio changelog: new text-to-speech models, API features, SDK releases and integrations, newest first, each entry linking to the page that documents it. ## Optional - [Pricing](https://kugelaudio.com/pricing) - [GitHub](https://github.com/kugelaudio) - [Support](mailto:hello@kugelaudio.com)