Skip to main content
import { KugelAudio } from 'kugelaudio';

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

// With custom options
const client = 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
});
OptionTypeDefaultDescription
apiKeystringrequiredAPI key or JWT token. Prefix with eu- to select the EU endpoint.
apiUrlstringhttps://api.kugelaudio.comAPI base URL. For self-hosted deployments, see Self-Hosted Deployment.
ttsUrlstringsame as apiUrlTTS server URL for WebSocket streaming.
timeoutnumber60000HTTP request timeout in milliseconds.
keepalivePingIntervalnumber | null20000Milliseconds 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).
regionRegion–'eu', 'us', or 'global'. 'eu' selects the direct EU endpoint.
isMasterKeybooleanfalseTreat apiKey as a master key (server-side use; bypasses billing).
isTokenbooleanfalseTreat apiKey as a JWT user token. Takes precedence over isMasterKey.
orgIdnumber–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 client = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'eu' });
The full KugelAudioOptions interface is documented in Types & Errors. Next: Generate Audio.