Configuration - KugelAudio

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.
`.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:

// 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 for details.

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 — one-shot generation, streaming, normalization, and word timestamps.