Configuration

from kugelaudio import KugelAudio

# Simple setup
client = KugelAudio(api_key="your_api_key")

# With custom options
client = KugelAudio(
    api_key="your_api_key",                # Required: Your API key
    api_url="https://api.kugelaudio.com",  # Optional: API base URL
    tts_url=None,                          # Optional: separate TTS/WebSocket URL
    timeout=60.0,                          # Optional: Request timeout in seconds
    keepalive_ping_interval=20.0,          # Optional: WS ping interval; None disables
    region=None,                           # Optional: "eu", "us", or "global"
)

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', 'us', or 'global'
});

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()
);

use std::time::Duration;

use kugelaudio::{KugelAudio, Region};

// Simple setup
let client = KugelAudio::new("your_api_key")?;

// With custom options
let configured_client = KugelAudio::builder("your_api_key")    // Required: your API key
    .api_url("https://api.kugelaudio.com")                      // Optional: API base URL
    .tts_url("https://api.kugelaudio.com")                      // Optional: separate TTS/WebSocket URL
    .timeout(Duration::from_secs(60))                           // Optional: request timeout
    .keepalive_ping_interval(Some(Duration::from_secs(20)))     // Optional: WS ping interval; None disables
    .region(Region::Eu)                                         // Optional: Eu, Us or Global
    .build()?;

#include <chrono>

#include <kugelaudio/kugelaudio.hpp>

// Simple setup
kugelaudio::Client client{"your_api_key"};

// With custom options
kugelaudio::ClientOptions options;
options.api_key = "your_api_key";                         // Required: your API key
options.api_url = "https://api.kugelaudio.com";           // Optional: API base URL
options.tts_url = "https://api.kugelaudio.com";           // Optional: separate TTS/WebSocket URL
options.timeout = std::chrono::seconds(60);               // Optional: request timeout
options.keepalive_ping_interval = std::chrono::seconds(20); // Optional: WS ping interval; std::nullopt disables
options.region = kugelaudio::Region::EU;                  // Optional: EU, US or Global
kugelaudio::Client configured_client{options};

import 'package:kugelaudio/kugelaudio.dart';

// Simple setup
final client = KugelAudio(apiKey: 'your_api_key');

// With custom options
final configuredClient = KugelAudio(
  apiKey: 'your_api_key',                         // Required: your API key
  apiUrl: 'https://api.kugelaudio.com',           // Optional: API base URL
  ttsUrl: null,                                   // Optional: separate TTS/WebSocket URL
  timeout: const Duration(seconds: 60),           // Optional: request timeout
  keepalivePingInterval: const Duration(seconds: 20), // Optional: WS ping interval; null disables
  region: null,                                   // Optional: Region.eu, Region.us or Region.global
);

# Not available in the Python SDK: it authenticates with API keys only.

// JWT user token: bill usage to an organisation
const user = new KugelAudio({ apiKey: jwt, isToken: true, orgId: 1253 });

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

// Not available in the Rust SDK: it authenticates with API keys only.

// Not available in the C++ SDK: it authenticates with API keys only.

// Not available in the Dart SDK: it authenticates with API keys only.

client = await KugelAudio.create(api_key="your_api_key")
print(client.is_connected())      # True once the pooled async socket is open
await client.aclose()             # Release HTTP + WebSocket resources

# KugelAudio is also a context manager, so resources are released automatically
with KugelAudio(api_key="your_api_key") as client:
    audio = client.tts.generate(text="Hello!", model_id="kugel-3.5", voice_id=1071)
    audio.save("output.wav")

await client.connect();            // Pre-open the WebSocket
console.log(client.isConnected()); // true once open
client.close();                    // Release the WebSocket + pending pings

// KugelAudio is AutoCloseable, so try-with-resources releases it automatically
try (KugelAudio client = KugelAudio.fromEnv()) {
    client.connect();                          // Block until the WebSocket is open
    System.out.println(client.isConnected());  // true once open
    // ... generate, stream ...
}                                              // close(): releases HTTP + WebSocket resources

let client = KugelAudio::new("your_api_key")?;
client.tts().connect(None).await?;           // Pre-open the WebSocket (None: kugel-3.5)
println!("{}", client.tts().is_connected()); // true once open
client.close().await;                        // Release the WebSocket + deliver pending reports

{
  kugelaudio::Client client{"your_api_key"};
  client.connect();                           // Block until the WebSocket is open
  std::cout << client.is_connected() << '\n'; // 1 once open
  // ... generate, stream ...
}  // The destructor calls close(): releases the WebSocket + delivers pending reports

final client = await KugelAudio.create(apiKey: 'your_api_key'); // Pre-opens the WebSocket
print(client.tts.isConnected);  // true once open
await client.close();           // Release HTTP + WebSocket resources + pending reports

# Option 1: prefix your API key
client = KugelAudio(api_key="eu-ka_your_api_key")

# Option 2: explicit region parameter
client = KugelAudio(api_key="ka_your_api_key", region="eu")

// 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' });

// Option 1: prefix your API key (the prefix is stripped before authentication)
KugelAudio client = new KugelAudio(
    KugelAudioOptions.builder("eu-ka_your_api_key").build()
);

// Option 2: explicit region
KugelAudio explicitEuClient = new KugelAudio(
    KugelAudioOptions.builder("ka_your_api_key")
        .region(Region.EU)
        .build()
);

// Option 1: prefix your API key (the prefix is stripped before authentication)
let client = KugelAudio::new("eu-ka_your_api_key")?;

// Option 2: explicit region
let explicit_eu_client = KugelAudio::builder("ka_your_api_key")
    .region(Region::Eu)
    .build()?;

// Option 1: prefix your API key (the prefix is stripped before authentication)
kugelaudio::Client client{"eu-ka_your_api_key"};

// Option 2: explicit region
kugelaudio::ClientOptions options;
options.api_key = "ka_your_api_key";
options.region = kugelaudio::Region::EU;
kugelaudio::Client explicit_eu_client{options};

// Option 1: prefix your API key (the prefix is stripped before authentication)
final client = KugelAudio(apiKey: 'eu-ka_your_api_key');

// Option 2: explicit region
final explicitEuClient = KugelAudio(apiKey: 'ka_your_api_key', region: Region.eu);