Audio Formats
Output encodings, the output_format token, G.711 telephony codecs, audio chunk fields, and the AI-generated audio marking (watermark + disclosure header).
On this page
This page is the single reference for what the TTS endpoints emit: the default
PCM encoding, the opt-in output_format codecs, the audio chunk wire format,
and the AI-generated audio marking (watermark and disclosure header).
Default format
- Encoding: PCM 16-bit signed little-endian (
pcm_s16le) - Channels: Mono (1 channel)
- Sample rate: 24000 Hz (default; native generation rate)
- Byte order: Little-endian
Other supported sample_rate values (8000, 16000, 22050, and 44100) use
server-side resampling. The combined native output_format tokens below do
not include pcm_44100; 44100 is available through the legacy integer
sample_rate field (and through the ElevenLabs-compatible format dialect).
Output formats (output_format)
By default the API emits linear PCM16 at sample_rate. To request a different
codec (for example G.711 µ-law/a-law for telephony), send the combined
output_format token instead of (or in addition to) sample_rate. The token
carries codec and rate as one value, so impossible combinations like
"µ-law at 24 kHz" cannot be expressed.
output_format | Codec | Rate | enc in audio frames | Bytes/sample |
|---|---|---|---|---|
pcm_8000 | Linear PCM16 | 8000 | pcm_s16le | 2 |
pcm_16000 | Linear PCM16 | 16000 | pcm_s16le | 2 |
pcm_22050 | Linear PCM16 | 22050 | pcm_s16le | 2 |
pcm_24000 | Linear PCM16 | 24000 | pcm_s16le | 2 |
ulaw_8000 | G.711 µ-law | 8000 | mulaw | 1 |
alaw_8000 | G.711 a-law | 8000 | alaw | 1 |
Notes:
- Backwards compatible. Omitting
output_formatis identical to the default behavior: you getpcm_s16leframes. The strict checks below only apply to requests that sendoutput_format. - Conflicts are rejected. Sending both
output_formatand an explicitly non-defaultsample_ratethat disagrees with the token's rate returns aVALIDATION_ERROR(HTTP 400 / WS error frame). The value24000is treated as the released SDKs' serialized wire default rather than evidence of an explicit conflicting choice. Prefer sending onlyoutput_format, or matching values. - Sticky streaming config. On Stream Input
and Multi-Context, a format sent on an
ordinary config/context message persists until another valid ordinary
message changes it. The acknowledged
update_settingscommand accepts only generation parameters and rejectsoutput_formatandsample_rate. - G.711 frame semantics. For
ulaw_8000/alaw_8000, audio frames carryenc: "mulaw"/"alaw",sr: 8000, andsamplesequals the byte length (1 byte/sample). Decode with the standard G.711 tables (e.g. Pythonaudioop.ulaw2lin(payload, 2);audioopleft the standard library in Python 3.13, so install theaudioop-ltspackage there). On REST, the response usesContent-Type: audio/basicandX-Audio-Format: mulaw/alaw.
Telephony example (µ-law 8 kHz)
{
"text": "Your verification code is 4 8 1 5.",
"voice_id": 1071,
"output_format": "ulaw_8000",
"language": "en"
}Audio chunk fields
Every WebSocket endpoint streams audio as JSON frames with these fields:
| Field | Type | Description |
|---|---|---|
audio | string | Base64-encoded audio data (encoding per enc) |
enc | string | Audio encoding (pcm_s16le, mulaw, or alaw) |
idx | integer | Chunk index (0-based) |
sr | integer | Sample rate in Hz |
samples | integer | Number of samples in this chunk |
chunk_id | integer | Text chunk ID (present on every native WebSocket audio frame) |
context_id | string | Context identifier (present on /ws/tts/multi) |
AI-generated audio marking
Every audio stream KugelAudio produces is marked as AI-generated in two independent ways, as required by EU AI Act Article 50 (Regulation (EU) 2024/1689):
- An in-band watermark embedded in the audio signal itself.
- A disclosure header on every audio response.
You do not need to enable anything: marking is mandatory and applied on every synthesis request, on every endpoint (native REST and WebSocket, ElevenLabs-compatible REST and WebSocket, and Vapi).
Disclosure header
Every HTTP audio response carries:
| Header | Value | Description |
|---|---|---|
X-KugelAudio-AI-Generated | true | The audio in this response is AI-generated |
WebSocket endpoints return the same header
(x-kugelaudio-ai-generated: true) in the connection handshake response. It
appears alongside the existing X-Sample-Rate and X-Audio-Format headers on
REST responses.
Watermark
Every output is watermarked in-band by the TTS engine before output encoding,
so every output_format (and proxy-side encodings such as MP3) carries it. The
mark is imperceptible and identifies the source platform or deployment, not an
individual request.
Detecting the watermark
pip install "kugelaudio[watermark]"from kugelaudio.watermark import WatermarkDetector
detector = WatermarkDetector()
result = detector.detect_file("speech.wav")
if result.ai_generated:
print(result.confidence, result.customer_id)The detector runs on numpy and works offline. Clips under one second are
rejected. Recovering the source id (customer_id) needs a few seconds of audio;
shorter clips report ai_generated with customer_id left unset.
Limitations
- Lossy encoding, added noise, and editing can weaken detection and attribution.
- The detector is trained on speech; a positive result on non-speech audio is unreliable.