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

# Configuration

> Client options, authentication modes, and region selection

```java theme={null}
import com.kugelaudio.sdk.KugelAudio;
import com.kugelaudio.sdk.KugelAudioOptions;
import java.time.Duration;

// Simple setup — reads KUGELAUDIO_API_KEY environment variable
KugelAudio client = KugelAudio.fromEnv();

// Full configuration
KugelAudio configuredClient = new KugelAudio(
    KugelAudioOptions.builder("your_api_key")
        .apiUrl("https://api.kugelaudio.com")        // REST + WebSocket base URL
        .ttsUrl("https://api.kugelaudio.com")        // Optional: separate TTS/WebSocket URL
        .timeout(Duration.ofSeconds(60))             // HTTP request timeout
        .autoConnect(true)                           // Pre-connect WebSocket (default: true)
        .keepalivePingInterval(Duration.ofSeconds(20)) // WS ping interval; null disables
        .build()
);
```

| Builder method                     | Type       | Default                      | Description                                                                                                |
| ---------------------------------- | ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `builder(apiKey)`                  | `String`   | required                     | API key or token. Prefix with `eu-` for the EU endpoint.                                                   |
| `.apiUrl(...)`                     | `String`   | `https://api.kugelaudio.com` | REST + WebSocket base URL. For self-hosted deployments, see [Self-Hosted Deployment](/guides/self-hosted). |
| `.ttsUrl(...)`                     | `String`   | same as `apiUrl`             | Separate TTS server URL for WebSocket streaming.                                                           |
| `.region(Region)`                  | `Region`   | –                            | `Region.EU`, `Region.US`, or `Region.GLOBAL`.                                                              |
| `.timeout(Duration)`               | `Duration` | 60 s                         | HTTP request timeout.                                                                                      |
| `.autoConnect(boolean)`            | `boolean`  | `true`                       | Pre-open the WebSocket at construction.                                                                    |
| `.keepalivePingInterval(Duration)` | `Duration` | 20 s                         | WebSocket ping interval to prevent idle timeouts. Pass `null` to disable.                                  |
| `.masterKey()`                     | –          | –                            | Treat the key as a master key (server-side; bypasses billing).                                             |
| `.token()`                         | –          | –                            | Treat the key as a JWT user token.                                                                         |
| `.orgId(int)`                      | `int`      | –                            | Organisation to bill usage against (required for token auth).                                              |

## Authentication modes

Most integrations use a project-scoped API key. For server-side and user-token
scenarios, set the mode on the builder:

```java theme={null}
// Master key (server-side, bypasses billing)
KugelAudio admin = new KugelAudio(
    KugelAudioOptions.builder("master_key").masterKey().build()
);

// JWT user token — bill usage to an organisation
KugelAudio user = new KugelAudio(
    KugelAudioOptions.builder(jwt).token().orgId(1253).build()
);
```

The resolved mode is available via `options.getAuthMode()`, which returns one of
`AuthMode.API_KEY`, `AuthMode.MASTER_KEY`, or `AuthMode.TOKEN`.

## Region Selection

Pin traffic to the direct EU endpoint when needed. See the [EU endpoint guide](/guides/regions) for details.

```java theme={null}
KugelAudio client = new KugelAudio(
    KugelAudioOptions.builder("eu-ka_your_api_key").build()
);

// Prefix is stripped before authentication

KugelAudio explicitEuClient = new KugelAudio(
    KugelAudioOptions.builder("ka_your_api_key")
        .region(Region.EU)
        .build()
);
```

***

Next: [Generate & Stream](/sdks/java/generate) — one-shot generation, streaming, normalization, and word timestamps.