kugelaudio 0.2.3 → 0.3.0

package/README.md

@@ -57,6 +57,33 @@ const client = new KugelAudio({
 });
 ```
 
+### Region Selection
+
+KugelAudio is available in multiple regions. The default is EU.
+
+| Region | Endpoint |
+|--------|----------|
+| `eu` | `api.kugelaudio.com` (default) |
+| `us` | `us-api.kugelaudio.com` |
+| `global` | `global-api.kugelaudio.com` (geo-routed) |
+
+**Option 1 — API key prefix** (simplest, works with env vars):
+
+```typescript
+const client = new KugelAudio({ apiKey: 'us-ka_your_api_key' });       // → US
+const client = new KugelAudio({ apiKey: 'global-ka_your_api_key' });   // → Global
+const client = new KugelAudio({ apiKey: 'eu-ka_your_api_key' });       // → EU (explicit)
+const client = new KugelAudio({ apiKey: 'ka_your_api_key' });           // → EU (default)
+```
+
+**Option 2 — `region` parameter**:
+
+```typescript
+const client = new KugelAudio({ apiKey: 'ka_your_api_key', region: 'us' });
+```
+
+The prefix is always stripped before authentication. Priority: `apiUrl` > `region` > key prefix > default (EU).
+
 ### Single URL Architecture
 
 The SDK uses a **single URL** for both REST API and WebSocket streaming. The TTS server provides both REST endpoints (`/v1/models`, `/v1/voices`) and WebSocket (`/ws/tts`) - no proxy needed, minimal latency.
@@ -84,10 +111,10 @@ const client = new KugelAudio({
 
 ## Available Models
 
-| Model ID | Name | Parameters | Description |
-|----------|------|------------|-------------|
-| `kugel-1-turbo` | Kugel 1 Turbo | 1.5B | Fast, low-latency model for real-time applications |
-| `kugel-1` | Kugel 1 | 7B | Premium quality model for pre-recorded content |
+| Model ID | Name | Description |
+|----------|------|-------------|
+| `kugel-1-turbo` | Kugel 1 Turbo | Fast, low-latency model for real-time applications |
+| `kugel-1` | Kugel 1 | Premium quality model for pre-recorded content |
 
 ### List Available Models
 
@@ -97,7 +124,6 @@ const models = await client.models.list();
 for (const model of models) {
   console.log(`${model.id}: ${model.name}`);
   console.log(`  Description: ${model.description}`);
-  console.log(`  Parameters: ${model.parameters}`);
   console.log(`  Max Input: ${model.maxInputLength} characters`);
   console.log(`  Sample Rate: ${model.sampleRate} Hz`);
 }
@@ -213,7 +239,6 @@ await client.tts.stream(
     },
     onFinal: (stats) => {
       console.log(`Total duration: ${stats.durationMs}ms`);
-      console.log(`Time to first audio: ${stats.ttfaMs}ms`);
       console.log(`Generation time: ${stats.generationMs}ms`);
       console.log(`RTF: ${stats.rtf}`);
     },
@@ -336,10 +361,11 @@ try {
 
 ```typescript
 interface KugelAudioOptions {
-  apiKey: string;      // Required
-  apiUrl?: string;     // Default: 'https://api.kugelaudio.com'
-  ttsUrl?: string;     // Default: same as apiUrl (backend proxies to TTS)
-  timeout?: number;    // Default: 60000 (ms)
+  apiKey: string;           // Required (can be prefixed with 'eu-', 'us-', or 'global-')
+  region?: Region;          // 'eu' | 'us' | 'global' (default: 'eu')
+  apiUrl?: string;          // Default: determined by region
+  ttsUrl?: string;          // Default: same as apiUrl
+  timeout?: number;         // Default: 60000 (ms)
 }
 ```
 
@@ -394,7 +420,6 @@ interface GenerationStats {
   totalSamples: number;   // Total samples generated
   durationMs: number;     // Audio duration in ms
   generationMs: number;   // Generation time in ms
-  ttfaMs: number;         // Time to first audio in ms
   rtf: number;           // Real-time factor
 }
 ```
@@ -418,7 +443,6 @@ interface Model {
   id: string;             // 'kugel-1-turbo' or 'kugel-1'
   name: string;           // Human-readable name
   description: string;    // Model description
-  parameters: string;     // Parameter count ('1.5B', '7B')
   maxInputLength: number; // Maximum input characters
   sampleRate: number;     // Output sample rate
 }
@@ -499,7 +523,7 @@ async function main() {
   console.log('Available Models:');
   const models = await client.models.list();
   for (const model of models) {
-    console.log(`  - ${model.id}: ${model.name} (${model.parameters})`);
+    console.log(`  - ${model.id}: ${model.name}`);
   }
 
   // List available voices