Client Configuration - KugelAudio

import { KugelAudio } from 'kugelaudio';

// Simple setup
const client = new KugelAudio({ apiKey: 'your_api_key' });

// With custom options
const configuredClient = new KugelAudio({
  apiKey: 'your_api_key',                // Required: Your API key
  apiUrl: 'https://api.kugelaudio.com',  // Optional: API base URL
  ttsUrl: undefined,                     // Optional: separate TTS/WebSocket URL
  timeout: 60000,                        // Optional: Request timeout in ms
  keepalivePingInterval: 20000,          // Optional: WS ping interval (ms); 0/null disables
  region: undefined,                     // Optional: 'eu' for the direct EU endpoint
});

Option	Type	Default	Description
`apiKey`	`string`	required	API key or JWT token. Prefix with `eu-` to select the EU endpoint.
`apiUrl`	`string`	`https://api.kugelaudio.com`	API base URL. For self-hosted deployments, see Self-Hosted Deployment.
`ttsUrl`	`string`	same as `apiUrl`	TTS server URL for WebSocket streaming.
`timeout`	`number`	`60000`	HTTP request timeout in milliseconds.
`keepalivePingInterval`	`number \| null`	`20000`	Milliseconds between WebSocket ping frames on the pooled connection. Set to `0` or `null` to disable. In browsers, pings are only sent via the `ws` package (skipped under native `WebSocket`).
`region`	`Region`	–	`'eu'`, `'us'`, or `'global'`. `'eu'` selects the direct EU endpoint.
`isMasterKey`	`boolean`	`false`	Treat `apiKey` as a master key (server-side use; bypasses billing).
`isToken`	`boolean`	`false`	Treat `apiKey` as a JWT user token. Takes precedence over `isMasterKey`.
`orgId`	`number`	–	Organisation to bill usage against. Required for token auth to record usage.

Authentication modes

Most integrations pass a project-scoped API key. For server-side and user-token scenarios, set the matching flag:

// Master key (server-side, bypasses billing)
const admin = new KugelAudio({ apiKey: 'master_key', isMasterKey: true });

// JWT user token — bill usage to an organisation
const user = new KugelAudio({ apiKey: jwt, isToken: true, orgId: 1253 });

The active mode is readable from getters: client.isMasterKey, client.isToken, client.orgId, plus client.apiKey, client.ttsUrl, and client.keepalivePingInterval.

Client lifecycle

await client.connect();            // Pre-open the WebSocket
console.log(client.isConnected()); // true once open
client.close();                    // Release the WebSocket + pending pings

Region Selection

Pin traffic to the direct EU endpoint when needed. See the EU endpoint guide for details.

// Option 1: prefix your API key
const client = new KugelAudio({ apiKey: 'eu-ka_your_api_key' });

// Option 2: explicit region parameter
const explicitEuClient = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'eu' });

The full KugelAudioOptions interface is documented in Types & Errors. Next: Generate Audio.