Configuration - KugelAudio

import com.kugelaudio.sdk.KugelAudio;
import com.kugelaudio.sdk.KugelAudioOptions;
import java.time.Duration;

// Simple setup: reads the 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 calls and each generate()/stream() call
        .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 On-Premise 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	Timeout for HTTP calls and for each complete `generate()` or `stream()` request. A generation that runs longer throws `ConnectionException("Request timed out")`; raise it for long texts.
`.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.
`.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. To authenticate with a user token instead, set the mode on the builder:

// 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() (AuthMode.API_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()
);

Diagnostics

The SDK reports its own connection and streaming failures back to KugelAudio so we can see problems that never reach our servers. It never sends your text, audio or credentials. See SDK Diagnostics for the full field list and the opt-out.

Next steps

Generate & Stream: one-shot generation, streaming, and word timestamps
LLM Sessions: streaming sessions for LLM output

Last modified on September 23, 2026