Skip to main content
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 client = 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 methodTypeDefaultDescription
builder(apiKey)StringrequiredAPI key or token. Prefix with eu- for the EU endpoint.
.apiUrl(...)Stringhttps://api.kugelaudio.comREST + WebSocket base URL. For self-hosted deployments, see Self-Hosted Deployment.
.ttsUrl(...)Stringsame as apiUrlSeparate TTS server URL for WebSocket streaming.
.region(Region)Region–Region.EU, Region.US, or Region.GLOBAL.
.timeout(Duration)Duration60 sHTTP request timeout.
.autoConnect(boolean)booleantruePre-open the WebSocket at construction.
.keepalivePingInterval(Duration)Duration20 sWebSocket 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.