Skip to content
KugelAudioDocs

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:

MethodWhen to use it
Custom speech vendorThe default. One HTTP endpoint, the full KugelAudio option grammar, plain-text input.
Azure Speech containerYour 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.

  1. Name the vendor

    Pick any name, for example kugelaudio. You'll use this name to select the vendor in your flows.

  2. Set the TTS HTTP URL
    Text
    https://api.kugelaudio.com/v1/cognigy

    Cognigy appends /synthesize/<vendor-name> to this URL automatically: enter the base URL exactly as shown, without a trailing path.

  3. Set the Authentication Token

    Paste your KugelAudio API key. Cognigy sends it as an Authorization: Bearer header, which KugelAudio authenticates on every request.

  4. Set the voice

    Enter the voice ID from step 1.

  5. Enable text-to-speech

    Turn on Use for text-to-speech. Leave Use for speech-to-text off: this endpoint provides TTS only.

  6. 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.

  7. 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:

Bash
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:

JSON
{
  "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:

StreamingResponse
OffA complete WAV file with Content-Length.
Onaudio/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:

Text
<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) valueResult
1887Voice 1887 with the existing defaults.
voice=1887The same as 1887.
voice=1887;style=consistentMore consistent prosody.
voice=1887;style=naturalNatural prosody.
voice=1887;style=expressiveMore expressive prosody.
voice=1887;style=expressive;normalize=falseExpressive prosody with text normalization disabled.
normalize=false;style=expressive;voice=1887The 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

ParameterValue
ContainerWAV (RIFF)
FormatLinear PCM, 16-bit signed, little-endian
Channels1 (mono)
Sample rateMatches 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.

  1. Choose the vendor

    Speech → Add speech service → Vendor: Microsoft Azure Speech Services.

  2. Switch to the container

    Leave Use hosted Azure service off and turn on Use Azure Docker container (on-prem).

  3. Set the container URLs
    Text
    Container URL for TTS:  https://api.kugelaudio.com/v1/azure
    Container URL for STT:  https://api.kugelaudio.com/v1/azure

    Enter 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.

  4. 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.

  5. 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.

  6. 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 nameResult
1887Voice 1887. The KugelAudio voice ID or handle, entered directly.
voice=1887;style=expressiveVoice 1887 with a style preset: the same grammar as the custom vendor, described in Configure voice style and text normalization.
de-DE-1887NeuralVoice 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-KatjaNeuralA 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 streamingWhat 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.
OffCognigy 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-pcm and riff-*-16bit-mono-pcm
  • raw-8khz-8bit-mono-mulaw / -alaw and their riff- forms
  • audio-16khz-*-mono-mp3 and audio-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

SymptomCause
401 Invalid API keySubscription key is not a valid KugelAudio key. Verify it with the curl above.
Every call uses the wrong voiceThe voice field still holds a Microsoft voice name, so the fallback voice answers. Enter a KugelAudio voice ID.
400 mentioning an output formatCognigy asked for a format KugelAudio does not emit. See Audio formats.
Audio plays only after a long pauseEnable text-to-speech streaming is off.
Speech-to-text never recognizes anythingExpected: 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:

Text
https://api.eu.kugelaudio.com/v1/cognigy   # custom speech vendor
https://api.eu.kugelaudio.com/v1/azure     # Azure Speech container

See Regions for the full list of endpoints.

Troubleshooting

SymptomCause
401 Invalid API keyThe Authentication Token is not a valid KugelAudio key. Verify it with the curl above.
401 No credentials providedThe Authentication Token field is empty.
404 Voice not foundThe voice ID does not exist or is not accessible to your organization.
400 mentioning languageThe language is not supported by KugelAudio.
400 mentioning typeThe vendor is sending SSML. KugelAudio accepts plain text; use prompting tags to shape speech instead.
400 mentioning a voice optionThe Custom (Voice) grammar is invalid. Check the option spelling and use only the documented values above.
405 or 404 on every requestThe 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 pauseStreaming is off on the vendor. Turn on Enable text-to-speech streaming.
Nothing changes after saving the vendorThe 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:

JSON
{ "error": "Invalid API key", "error_code": "UNAUTHORIZED", "code": 401 }

See Error codes for the full list.