Authentication

Protected API requests require authentication using an API key. The health and model-catalog endpoints are public; synthesis, voice, and dictionary endpoints authenticate the caller. This page explains how to obtain and use your API key.

Getting Your API Key

Sign up at kugelaudio.com
Go to your Dashboard
In the sidebar, open Team & Settings → API Keys
Click Create key and give it a descriptive name (for example, “Production Server”)
Copy and securely store your key

API keys are shown only once when created. Store them securely! If you lose a key, you’ll need to create a new one.

Using Your API Key

HTTP Requests

Include your API key in the Authorization header using Bearer token format:

curl -X POST "https://api.kugelaudio.com/v1/tts/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello, world!", "model_id": "kugel-3", "voice_id": 1071}'

The native API also accepts the equivalent X-API-Key header:

curl "https://api.kugelaudio.com/v1/voices?limit=1" \
  -H "X-API-Key: YOUR_API_KEY"

The api_key query parameter is also accepted, but use a header for HTTP requests so the secret is less likely to appear in URLs and access logs.

WebSocket Connections

WebSocket connections accept the same credentials. Pass Authorization: Bearer or X-API-Key in the handshake headers when your client library supports custom headers:

import asyncio
import os

import websockets


async def main():
    async with websockets.connect(
        "wss://api.kugelaudio.com/ws/tts",
        additional_headers={"Authorization": f"Bearer {os.environ['KUGELAUDIO_API_KEY']}"},
    ) as ws:
        pass  # send TTS messages; see the WebSocket reference


asyncio.run(main())

Server-side clients that cannot set handshake headers can use the query form:

// Node.js, using the `ws` package
import WebSocket from 'ws';

const ws = new WebSocket(
  `wss://api.kugelaudio.com/ws/tts?api_key=${process.env.KUGELAUDIO_API_KEY}`,
);

Never open these connections from browser code: the key would be visible to anyone using the page. Proxy browser traffic through your own server.

SDK Usage

Python
JavaScript
cURL

from kugelaudio import KugelAudio
import os

# Pass directly
client = KugelAudio(api_key="YOUR_API_KEY")

# Or read the environment variable explicitly
client = KugelAudio(api_key=os.environ["KUGELAUDIO_API_KEY"])

import { KugelAudio } from 'kugelaudio';

// Read the key from the environment (Node.js)
const client = new KugelAudio({ apiKey: process.env.KUGELAUDIO_API_KEY! });

# Set your API key as an environment variable
export KUGELAUDIO_API_KEY="YOUR_API_KEY"

# Then reference it in requests
curl "https://api.kugelaudio.com/v1/voices?limit=1" \
  -H "Authorization: Bearer $KUGELAUDIO_API_KEY"

Environment Variables

For security, we recommend using environment variables instead of hardcoding API keys:

# .env file
KUGELAUDIO_API_KEY=your_api_key_here

The Python and JavaScript clients require the key in their constructors; read KUGELAUDIO_API_KEY from your process environment as shown above. The Java client also provides KugelAudio.fromEnv(). Traffic goes to the canonical geo-routed endpoint by default; see Regions to pin traffic to the EU endpoint.

API Key Security

Never expose keys in client-side code

API keys should only be used in server-side code. Never include them in:

Frontend JavaScript
Mobile app source code
Public repositories
Client-side environment variables

Rotate keys regularly

Create new API keys periodically and delete old ones. This limits the impact of any potential key exposure.

Use separate keys for environments

Create separate API keys for development, staging, and production. This makes it easier to rotate keys and track usage.

Managing API Keys

Create keys as described in Getting Your API Key.

Deleting Keys

If a key is compromised:

Create a new key and update your applications
In Team & Settings → API Keys, click Delete on the old key and confirm

API-key lookups are cached briefly. A deletion can take roughly 30 seconds to propagate to an ingress process, so rotate applications before deleting the old key and do not rely on deletion as an instantaneous session kill.

Key Scope

Dashboard API keys are scoped to a project. Resource APIs such as dictionaries enforce that project scope.

Authentication Errors

401 Unauthorized

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

When the request carries no credentials at all, error reads "No credentials provided. Use ?api_key=, X-API-Key, or Authorization: Bearer." Causes:

No credentials in the request
Invalid or deleted API key
Malformed header format

Solutions:

Send the key as Authorization: Bearer YOUR_API_KEY, X-API-Key: YOUR_API_KEY, or the api_key query parameter
Verify the API key is correct and has not been deleted
For the EU endpoint, send the key without the eu- prefix (only the SDKs strip it; see Regions)

403 Forbidden

{
  "error": "Forbidden",
  "error_code": "UNAUTHORIZED",
  "code": 403
}

Causes:

Trying to access resources from another account
Using a key whose project does not own the requested resource
Calling voice-management operations with a credential that has no organization/user identity

Solutions:

Verify you’re using the correct API key
Verify the key belongs to the resource’s project or organization

Testing Authentication

Verify your API key is working:

curl --fail-with-body "https://api.kugelaudio.com/v1/voices?limit=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

A valid key receives a 200 voice-page response. A missing, invalid, or deleted key receives the standard 401 UNAUTHORIZED error envelope. Do not use /v1/models for this check: the model catalog is public and cannot verify a key.

Get started

Build a voice agent

Generate audio

Voices

Enhance audio

Hosting and deployment

SDK Reference

API Reference

Getting Your API Key

Using Your API Key

HTTP Requests

WebSocket Connections

SDK Usage

Environment Variables

API Key Security

Managing API Keys

Deleting Keys

Key Scope

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication

Next steps

Quick Start

Errors

​Getting Your API Key

​Using Your API Key

​HTTP Requests

​WebSocket Connections

​SDK Usage

​Environment Variables

​API Key Security

​Managing API Keys

​Deleting Keys

​Key Scope

​Authentication Errors

​401 Unauthorized

​403 Forbidden

​Testing Authentication

​Next steps

Quick Start

Errors

Getting Your API Key

Using Your API Key

HTTP Requests

WebSocket Connections

SDK Usage

Environment Variables

API Key Security

Managing API Keys

Deleting Keys

Key Scope

Authentication Errors

401 Unauthorized

403 Forbidden

Testing Authentication

Next steps