Cognigy Integration
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.
On this page
KugelAudio has a built-in Cognigy Voice Gateway custom-vendor endpoint: no proxy server needed. Register KugelAudio once as a speech service in Cognigy's Self-Service Portal, then select it in your flows.
There are two ways to register KugelAudio, and they are interchangeable, pick one:
| Method | When to use it |
|---|---|
| Custom speech vendor | The default. One HTTP endpoint, the full KugelAudio option grammar, plain-text input. |
| Azure Speech container | Your Cognigy plan has no custom-vendor option, or your deployment is standardized on the Microsoft Azure Speech Services vendor. |
Setup
1. Get your KugelAudio API key and a voice ID
- API key: open the KugelAudio dashboard, then go to Settings → API Keys.
- Voice ID: open the KugelAudio dashboard, go to Voices, pick a voice, and copy its ID. The numeric ID or the voice handle both work.
2. Add KugelAudio as a speech service
In the Cognigy Voice Gateway Self-Service Portal, go to Speech → Add speech service and choose a custom vendor.
- Name the vendor
Pick any name, for example
kugelaudio. You'll use this name to select the vendor in your flows. - Set the TTS HTTP URLText
https://api.kugelaudio.com/v1/cognigyCognigy appends
/synthesize/<vendor-name>to this URL automatically: enter the base URL exactly as shown, without a trailing path. - Set the Authentication Token
Paste your KugelAudio API key. Cognigy sends it as an
Authorization: Bearerheader, which KugelAudio authenticates on every request. - Set the voice
Enter the voice ID from step 1.
- Enable text-to-speech
Turn on Use for text-to-speech. Leave Use for speech-to-text off: this endpoint provides TTS only.
- Enable streaming (recommended)
Turn on Enable text-to-speech streaming so audio starts playing while it is still being generated, instead of after the whole utterance is synthesized.
- Choose the account scope
Select which Cognigy accounts may use this vendor, then save.
3. Select the vendor in your flow
Registering the vendor does not switch your flow over on its own. Set the vendor name in the Custom parameter of the relevant nodes: Set Session Config, Say, Question, Optional Question, or Session Speech Parameters Config.
Verify your API key first
If synthesis fails, check the key on its own before changing anything in Cognigy:
curl "https://api.kugelaudio.com/v1/voices?limit=1" \
-H "X-API-Key: YOUR_KUGELAUDIO_API_KEY"200 means the key is good. 401 Invalid API key means the key is wrong, truncated, or from a different environment: a KugelAudio project key looks like sk-kug-proj_lu_… and is long, so a partial copy-paste is the usual cause.
How it works
Cognigy sends one POST per utterance:
{
"text": "Guten Tag, wie kann ich Ihnen helfen?",
"voice": "1887",
"language": "de-DE",
"type": "text",
"encoding": "linear16",
"sample_rate": 8000
}encoding and sample_rate are sent only when TTS streaming is enabled on the vendor, and they select how the audio comes back:
| Streaming | Response |
|---|---|
| Off | A complete WAV file with Content-Length. |
| On | audio/wav sent chunked: a WAV header followed by linear16 PCM at the requested sample rate, flushed as the model produces it. |
Language tags are BCP-47 (de-DE, en-US). KugelAudio uses the language part and ignores the region, so de-DE and de-AT both select German. See Voices for the languages each voice supports.
Configure voice style and text normalization
Cognigy does not forward arbitrary option objects to custom TTS providers. To configure KugelAudio per request, put the optional settings in Cognigy's Custom (Voice) field:
<setting>[;<setting>...]
setting = voice=<voice>
| style=<consistent|natural|expressive>
| normalize=<true|false>Existing configurations that contain only a voice ID or handle continue to
work unchanged. In configured form, voice is required exactly once and all
settings can appear in any order.
| Custom (Voice) value | Result |
|---|---|
1887 | Voice 1887 with the existing defaults. |
voice=1887 | The same as 1887. |
voice=1887;style=consistent | More consistent prosody. |
voice=1887;style=natural | Natural prosody. |
voice=1887;style=expressive | More expressive prosody. |
voice=1887;style=expressive;normalize=false | Expressive prosody with text normalization disabled. |
normalize=false;style=expressive;voice=1887 | The same settings in a different order. |
The setting names and supported values are case-insensitive. style defaults
to the existing natural behavior and normalize defaults to true; unknown,
duplicate, or malformed options return a 400 VALIDATION_ERROR instead of
silently falling back. See
Text processing for what normalization does.
Audio format
| Parameter | Value |
|---|---|
| Container | WAV (RIFF) |
| Format | Linear PCM, 16-bit signed, little-endian |
| Channels | 1 (mono) |
| Sample rate | Matches sample_rate when streaming; otherwise 24000 Hz |
Supported sample rates are 8000, 16000, 22050, 24000, and 44100. Cognigy Voice Gateway requests 8000 for streaming telephony audio.
Alternative: register KugelAudio as an Azure Speech container
KugelAudio's ingress also answers the Azure Speech on-premises container contract, so you can register it under Cognigy's built-in Microsoft Azure Speech Services vendor instead of as a custom vendor. Nothing Azure runs; the URL points at KugelAudio.
- Choose the vendor
Speech → Add speech service → Vendor: Microsoft Azure Speech Services.
- Switch to the container
Leave Use hosted Azure service off and turn on Use Azure Docker container (on-prem).
- Set the container URLsText
Container URL for TTS: https://api.kugelaudio.com/v1/azure Container URL for STT: https://api.kugelaudio.com/v1/azureEnter the base URL exactly as shown, with no path after it.
Cognigy makes both fields mandatory even when speech-to-text is switched off. KugelAudio serves TTS at that URL; the same URL also answers the Azure recognition contract, but only as a stub that always returns
NoMatch. See Speech-to-text below. - Set the subscription key
Paste your KugelAudio API key into Subscription key (if required). Cognigy sends it as
Ocp-Apim-Subscription-Key, which KugelAudio authenticates on every request. - Enable text-to-speech and streaming
Turn on Use for text-to-speech and Enable text-to-speech streaming. Leave Use for speech-to-text off.
- Choose the voice
Cognigy's Azure voice list is a fixed list of Microsoft voice names and cannot show KugelAudio voices, so enter a KugelAudio voice yourself. See Choosing a voice.
Choosing a voice
The voice name arrives inside the SSML that Cognigy generates. KugelAudio reads it in this order:
| Voice name | Result |
|---|---|
1887 | Voice 1887. The KugelAudio voice ID or handle, entered directly. |
voice=1887;style=expressive | Voice 1887 with a style preset: the same grammar as the custom vendor, described in Configure voice style and text normalization. |
de-DE-1887Neural | Voice 1887. For fields that insist on Microsoft's <language>-<REGION>-<Name> shape, the digits in the name part are read as the voice ID. |
de-DE-KatjaNeural | A default KugelAudio voice (973). A genuine Microsoft voice name has no KugelAudio equivalent, so synthesis falls back rather than failing a live call. |
Streaming
Both of Cognigy's code paths are served at the same URL:
| Enable text-to-speech streaming | What happens |
|---|---|
| On (recommended) | Cognigy opens a WebSocket to the URL and speaks the Microsoft Speech SDK protocol. Audio starts playing at KugelAudio's time-to-first-audio instead of after the whole utterance. |
| Off | Cognigy POSTs the SSML to the URL. For raw-* and MP3 output formats KugelAudio sends the audio in chunks as it is generated, the way Azure's own REST endpoint does; riff-* (WAV) formats arrive as one complete file. |
Audio formats
KugelAudio accepts Azure's X-Microsoft-OutputFormat tokens (and the equivalent WebSocket setting) at the sample rates it supports, 8000, 16000, 22050, 24000 and 44100 Hz:
raw-*-16bit-mono-pcmandriff-*-16bit-mono-pcmraw-8khz-8bit-mono-mulaw/-alawand theirriff-formsaudio-16khz-*-mono-mp3andaudio-24khz-*-mono-mp3
An unsupported token returns 400 rather than being resampled silently. Cognigy Voice Gateway asks for raw-8khz-16bit-mono-pcm or audio-16khz-32kbitrate-mono-mp3.
Speech-to-text
The Azure recognition endpoints under /v1/azure exist only so Cognigy's mandatory Container URL for STT field validates. They always answer NoMatch and never transcribe.
KugelAudio's real speech to text is the speech-to-text API. It speaks neither the Azure recognition protocol nor Cognigy's custom-vendor STT contract (the custom-vendor endpoint is TTS only), so Cognigy cannot use it as its recognizer; call the API directly from your own code.
Azure container troubleshooting
| Symptom | Cause |
|---|---|
401 Invalid API key | Subscription key is not a valid KugelAudio key. Verify it with the curl above. |
| Every call uses the wrong voice | The voice field still holds a Microsoft voice name, so the fallback voice answers. Enter a KugelAudio voice ID. |
400 mentioning an output format | Cognigy asked for a format KugelAudio does not emit. See Audio formats. |
| Audio plays only after a long pause | Enable text-to-speech streaming is off. |
| Speech-to-text never recognizes anything | Expected: the STT half is a stub. Turn Use for speech-to-text off. |
Synthesis fails with WebSocket close 4003 (or HTTP 402 with streaming off) | Your organization is out of credit. Top up in the dashboard. |
Synthesis fails with WebSocket close 4029 (or HTTP 429) | Rate or concurrency limit reached. See Limits. |
With streaming on, a failed synthesis closes the WebSocket with the error code and its message instead of returning empty audio, so the synthesis fails visibly rather than playing silence on the call. Every request, including failed ones, appears on the Logs page of your dashboard.
Limits
Each organization has a rate limit and a cap on concurrent generations. A live
phone deployment can hold several calls open at once, so the concurrency cap is
usually the one that matters: when it is exceeded, synthesis is rejected with
429 RATE_LIMITED (WebSocket close 4029 with streaming on).
Check your organization's limits in the dashboard before going live, and contact us if you need them raised for production traffic. See Error codes for the exact responses.
Regions
To keep traffic and data inside the EU, use the regional host instead:
https://api.eu.kugelaudio.com/v1/cognigy # custom speech vendor
https://api.eu.kugelaudio.com/v1/azure # Azure Speech containerSee Regions for the full list of endpoints.
Troubleshooting
| Symptom | Cause |
|---|---|
401 Invalid API key | The Authentication Token is not a valid KugelAudio key. Verify it with the curl above. |
401 No credentials provided | The Authentication Token field is empty. |
404 Voice not found | The voice ID does not exist or is not accessible to your organization. |
400 mentioning language | The language is not supported by KugelAudio. |
400 mentioning type | The vendor is sending SSML. KugelAudio accepts plain text; use prompting tags to shape speech instead. |
400 mentioning a voice option | The Custom (Voice) grammar is invalid. Check the option spelling and use only the documented values above. |
405 or 404 on every request | The TTS HTTP URL is wrong. It must be the base URL https://api.kugelaudio.com/v1/cognigy, with no path after it. |
| Audio plays only after a long pause | Streaming is off on the vendor. Turn on Enable text-to-speech streaming. |
| Nothing changes after saving the vendor | The flow still points at the old provider. Set the vendor name in the node's Custom parameter. |
Every error response carries a readable message, which Cognigy records in its logs:
{ "error": "Invalid API key", "error_code": "UNAUTHORIZED", "code": 401 }See Error codes for the full list.