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

# Client Configuration

> Configure the KugelAudio client — options, authentication modes, regions, and lifecycle

```typescript theme={null}
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](/guides/self-hosted).                                                                                                   |
| `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:

```typescript theme={null}
// 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

```typescript theme={null}
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](/guides/regions) for details.

```typescript theme={null}
// 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](/sdks/javascript/types#kugelaudiooptions). Next: [Generate Audio](/sdks/javascript/generate).