Skip to content
KugelAudioDocs

Generate Speech API

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.

Generate audio from text. The response streams raw audio bytes as they are produced.

POST/v1/tts/generate
curl -X POST "https://api.kugelaudio.com/v1/tts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "text": "Hello, this is a quick test of the speech API.",
    "model_id": "kugel-3.5",
    "voice_id": 1071,
    "cfg_scale": 2.0
  }'
0:00 / --:--
Samantha FerrisEnglishkugel-3.5

Request Body

This is the canonical parameter reference for TTS generation. The WebSocket endpoints accept the same fields (plus their own session controls, see Stream Input).

text
string
body
required

The text to convert to speech. It must contain at least 2 characters after trimming whitespace and is limited to 10,000 characters. Text with nothing to speak, such as "!!", is refused with 400 and "error": "text contains nothing to speak". Supports inline <break>, <spell>, and <prosody rate> tags. Other SSML has no stable stripping or interpretation contract; remove it before sending text (see Prompting). Shorter text or text over 10,000 characters returns 400 VALIDATION_ERROR; text over the model's or your plan's per-request limit returns 413 VALIDATION_ERROR. Streaming chunks on the WebSocket endpoints are exempt from the 2-character minimum.

model_id
string
bodydefault: kugel-3.5

The model to use: kugel-3.5 (the default, our newest model) or kugel-3; see Models to choose. The legacy IDs listed on Models remain accepted for backwards compatibility. The legacy request field model is also accepted as an alias when model_id is omitted; do not send both. Unknown IDs return 400 VALIDATION_ERROR. Accepted model IDs are billed and shown in Dashboard usage as requested, even when they route through the current production model.

voice_id
integer | string
body
required

The numeric voice ID or the voice handle. Required: there is no default voice. A request without a voice_id is rejected with 400 MISSING_VOICE_ID; a voice_id that doesn't exist (or isn't visible to your API key) returns 404 NOT_FOUND.

cfg_scale
number
bodydefault: 2.0

Classifier-free guidance scale. Range: 1.2-2.5 (inclusive); values outside this range are clamped into it. Higher values = more expressive.

temperature
number
body

Sampling variance (0.0 to 1.0). 0, the default, always takes the model's most likely pacing decision; higher values sample it for more variation between takes. See temperature guidance. Values outside the range return 400 VALIDATION_ERROR. When omitted, uses the engine default, consistently with the streaming endpoints.

max_new_tokens
integer
bodydefault: 2048

Maximum tokens to generate. Range: 1-2048. Limits output length. Values outside the range return 400 VALIDATION_ERROR.

sample_rate
integer
bodydefault: 24000

Output sample rate in Hz. Options: 8000, 16000, 22050, 24000, 44100.

Audio is generated natively at 24kHz. Other rates use server-side resampling. Any other value returns 400 VALIDATION_ERROR.

output_format
string
body

Combined codec + rate token (e.g. ulaw_8000) for non-PCM output such as G.711 telephony codecs. Opt-in; when set it is authoritative and must not contradict an explicitly non-default sample_rate. The wire-default sample_rate: 24000 is ignored when resolving the token. See Audio formats.

normalize
boolean
bodydefault: true

Enable text normalization (converts numbers, dates, etc. to spoken words).

Set language when you know it; without it each sentence is normalized in the language it is written in (Text normalization).

language
string
body

ISO 639-1 language code for text normalization (e.g., 'de', 'en', 'fr').

Supported: de, en, fr, es, it, pt, nl, pl, sv, da, no, fi, cs, hu, ro, el, uk, bg, tr, vi, ar, hi, zh, ja, ko, sk, sl, hr, sr, ru, he, fa, ur, bn, ta, yue, th, id, ms

If not provided, the server recognizes each sentence's language from its words, and uses the voice's primary language (English if it has none) when a sentence gives no clear sign (Text normalization). Other values return 400 VALIDATION_ERROR.

word_timestamps
boolean
bodydefault: false

WebSocket endpoints only. Enable word-level timestamp alignment. See Word timestamps. Not accepted by this REST endpoint: requests are strictly validated, so sending it here returns 400 Bad Request. Use a WebSocket endpoint or an SDK instead.

speed
number
bodydefault: 1.0

Playback speed multiplier. Range: 0.8 (20% slower) to 1.2 (20% faster).

Uses pitch-preserving time-stretching (WSOLA) so the voice pitch stays natural at any speed. Applies to the whole request; wrap text in <prosody rate="slow|medium|fast|0.8-1.2"> to override the rate for a span (see Speed). Values outside the range return 400 VALIDATION_ERROR; unlike cfg_scale, speed is not clamped.

project_id
integer
body

Project whose custom dictionaries should be loaded. Optional for a project API key: when omitted, the key's own project is used, so a key issued per end customer (see Projects) applies that customer's dictionaries without naming the project. A caller without a project that omits it generates without project dictionaries. When you name a project, the API verifies that the caller can access it if dictionary_ids is non-empty. A bare inaccessible project_id currently falls back to generation without a dictionary; an explicit selection fails with 403 UNAUTHORIZED.

dictionary_ids
integer[]
body

Per-request dictionary selection.

  • Omitted: all active dictionaries of the request's project (project_id, or the API key's own project when project_id is omitted) apply, filtered by language; a caller without a project loads none.
  • []: no dictionary applies to this request.
  • [7, 9]: exactly those dictionaries apply, including inactive ones, bypassing the language filter.

A non-empty list needs a project: project_id, or the API key's own project; a caller without either gets a 400. IDs must belong to that project; unknown IDs return a 400 before generation starts. Maximum 50 IDs.

Temperature guidance

temperature controls how the model decides where speech segments start and end, which shapes pacing and where pauses and sentence ends fall. At 0, and when the field is omitted, the model always takes its most likely decision. Above 0 those decisions are sampled, more freely as the value rises, so regenerating the same text varies more between takes.

The effect is subtle. Two renders of the same text differ at every temperature, because the acoustic sampler is randomized; temperature adds to that variation rather than switching it on. In our measurements on long German and English paragraphs and on number-heavy text, every value from 0 to 1 kept content accuracy, voice similarity and audio quality at the level of 0.

Use caseSuggested value
IVR prompts, compliance reads, numbers and IDsomit, or 0.0
General voiceover, conversational UX0.0 to 0.5
Narration where takes should differ more0.5 to 1.0

Explicit values override the default; a client preset that sends a value is an explicit override.

Spell Tags

Wrap text in <spell> to read it letter by letter (emails, codes, acronyms). Spell content bypasses normalization. See Spell.

Response

Returns the requested raw encoding as a streaming binary response. The default is PCM16 (audio/pcm); G.711 output uses audio/basic. For encoding details and the watermark, see Audio formats.

Response Headers:

HeaderValueDescription
Content-Typeaudio/pcmaudio/pcm for PCM16; audio/basic for G.711
X-Sample-Rate24000Resolved output sample rate (shown: default)
X-Audio-Formatpcm_s16leResolved encoding: pcm_s16le, mulaw, or alaw (shown: default)
X-KugelAudio-AI-GeneratedtrueAI-generated audio disclosure (see Audio formats)

With the default format, the response body is raw PCM 16-bit signed little-endian audio data streamed as binary chunks.

The response example on this page plays the audio that the example request returns, saved as MP3 so your browser can play it.

Example

Errors

See Error Codes for the full TTS error lookup table, including HTTP status codes, WebSocket close codes, and rate-limit behavior.