> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kugelaudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cognigy Integration

> Use KugelAudio as a custom speech vendor in Cognigy Voice Gateway

KugelAudio has a built-in [Cognigy Voice Gateway](https://docs.cognigy.com/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.

<Note>
  Cognigy's **built-in ElevenLabs provider is hosted-only** and has no custom base-URL field, so it cannot be pointed at KugelAudio. Add KugelAudio as a **custom speech vendor** instead, as described below.
</Note>

## Setup

### 1. Get your KugelAudio API key and a voice ID

* **API key** — open the [KugelAudio dashboard](https://kugelaudio.com/dashboard), then go to Settings → API Keys.
* **Voice ID** — open the [KugelAudio dashboard](https://kugelaudio.com/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.

<Steps>
  <Step title="Name the vendor">
    Pick any name, for example `kugelaudio`. You'll use this name to select the vendor in your flows.
  </Step>

  <Step title="Set the TTS HTTP URL">
    ```
    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.
  </Step>

  <Step title="Set the Authentication Token">
    Paste your KugelAudio API key. Cognigy sends it as an `Authorization: Bearer` header, which KugelAudio authenticates on every request.
  </Step>

  <Step title="Set the voice">
    Enter the voice ID from step 1.
  </Step>

  <Step title="Enable text-to-speech">
    Turn on **Use for text-to-speech**. Leave **Use for speech-to-text** off — this endpoint provides TTS only.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Choose the account scope">
    Select which Cognigy accounts may use this vendor, then save.
  </Step>
</Steps>

### 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`.

<Warning>
  If you skip this step the flow keeps using whichever provider it used before, and nothing appears to change.
</Warning>

## Verify your API key first

If synthesis fails, check the key on its own before changing anything in Cognigy:

```bash theme={null}
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 theme={null}
{
  "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](/features/voices) for the languages each voice supports.

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

## 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` and the caller hears nothing.

Check your organization's limits in the [dashboard](https://kugelaudio.com/dashboard)
before going live, and contact us if you need them raised for production traffic.
See [Error codes](/api-reference/errors) for the exact responses.

## Regions

To keep traffic and data inside the EU, use the regional endpoint instead:

```
https://api.eu.kugelaudio.com/v1/cognigy
```

See [Regions](/guides/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](/prompting/overview) to shape speech instead. |
| `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:

```json theme={null}
{ "error": "Invalid API key", "error_code": "UNAUTHORIZED", "code": 401 }
```

See [Error codes](/api-reference/errors) for the full list.