kugelaudio 0.1.1 → 0.1.3

package/README.md

@@ -31,7 +31,7 @@ const client = new KugelAudio({ apiKey: 'your_api_key' });
 // Generate speech
 const audio = await client.tts.generate({
   text: 'Hello, world!',
-  model: 'kugel-one-turbo',
+  model: 'kugel-1-turbo',
 });
 
 // Create a playable blob (browser)
@@ -86,8 +86,8 @@ const client = new KugelAudio({
 
 | Model ID | Name | Parameters | Description |
 |----------|------|------------|-------------|
-| `kugel-one-turbo` | Kugel One Turbo | 1.5B | Fast, low-latency model for real-time applications |
-| `kugel-one` | Kugel One | 7B | Premium quality model for pre-recorded content |
+| `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 |
 
 ### List Available Models
 
@@ -144,7 +144,7 @@ Generate complete audio and receive it all at once:
 ```typescript
 const audio = await client.tts.generate({
   text: 'Hello, this is a test of the KugelAudio text-to-speech system.',
-  model: 'kugel-one-turbo',  // 'kugel-one-turbo' (fast) or 'kugel-one' (quality)
+  model: 'kugel-1-turbo',  // 'kugel-1-turbo' (fast) or 'kugel-1' (quality)
   voiceId: 123,              // Optional: specific voice ID
   cfgScale: 2.0,             // Guidance scale (1.0-5.0)
   maxNewTokens: 2048,        // Maximum tokens to generate
@@ -169,7 +169,7 @@ import { createWavBlob } from 'kugelaudio';
 
 const audio = await client.tts.generate({
   text: 'Hello, world!',
-  model: 'kugel-one-turbo',
+  model: 'kugel-1-turbo',
 });
 
 // Create WAV blob for playback
@@ -198,7 +198,7 @@ Receive audio chunks as they are generated for lower latency:
 await client.tts.stream(
   {
     text: 'Hello, this is streaming audio.',
-    model: 'kugel-one-turbo',
+    model: 'kugel-1-turbo',
   },
   {
     onOpen: () => {
@@ -300,7 +300,7 @@ interface KugelAudioOptions {
 ```typescript
 interface GenerateOptions {
   text: string;            // Required: Text to synthesize
-  model?: string;          // Default: 'kugel-one-turbo'
+  model?: string;          // Default: 'kugel-1-turbo'
   voiceId?: number;        // Optional: Voice ID
   cfgScale?: number;       // Default: 2.0
   maxNewTokens?: number;   // Default: 2048
@@ -364,7 +364,7 @@ interface StreamCallbacks {
 
 ```typescript
 interface Model {
-  id: string;             // 'kugel-one-turbo' or 'kugel-one'
+  id: string;             // 'kugel-1-turbo' or 'kugel-1'
   name: string;           // Human-readable name
   description: string;    // Model description
   parameters: string;     // Parameter count ('1.5B', '7B')
@@ -467,7 +467,7 @@ async function main() {
   await client.tts.stream(
     {
       text: 'Welcome to KugelAudio. This is an example of high-quality text-to-speech synthesis.',
-      model: 'kugel-one-turbo',
+      model: 'kugel-1-turbo',
     },
     {
       onChunk: (chunk) => {

package/dist/index.d.mts

@@ -47,7 +47,7 @@ interface Voice {
 interface GenerateOptions {
     /** Text to synthesize */
     text: string;
-    /** Model to use (default: 'kugel-one-turbo') */
+    /** Model to use: 'kugel-1-turbo' (1.5B, fast) or 'kugel-1' (7B, premium). Default: 'kugel-1-turbo' */
     model?: string;
     /** Voice ID to use */
     voiceId?: number;
@@ -153,6 +153,8 @@ interface StreamCallbacks {
 interface KugelAudioOptions {
     /** Your KugelAudio API key */
     apiKey: string;
+    /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
+    isMasterKey?: boolean;
     /** API base URL (default: https://api.kugelaudio.com) */
     apiUrl?: string;
     /** TTS server URL (default: https://eu.kugelaudio.com) */
@@ -200,16 +202,50 @@ declare class VoicesResource {
  */
 declare class TTSResource {
     private client;
+    private wsConnection;
+    private wsUrl;
+    private pendingRequests;
+    private requestCounter;
     constructor(client: KugelAudio);
     /**
      * Generate audio from text with streaming via WebSocket.
      * Returns complete audio after all chunks are received.
      */
     generate(options: GenerateOptions): Promise<AudioResponse>;
+    /**
+     * Build the WebSocket URL with appropriate auth param.
+     */
+    private buildWsUrl;
+    /**
+     * Get or create a WebSocket connection for connection pooling.
+     * This avoids the ~220ms connect overhead on each request.
+     */
+    private getConnection;
+    /**
+     * Setup message handler for pooled connection.
+     */
+    private setupMessageHandler;
     /**
      * Stream audio from text via WebSocket.
+     * Uses connection pooling for faster TTFA (~180ms vs ~400ms).
+     *
+     * @param options - Generation options
+     * @param callbacks - Stream callbacks
+     * @param reuseConnection - If true (default), reuse WebSocket connection
+     */
+    stream(options: GenerateOptions, callbacks: StreamCallbacks, reuseConnection?: boolean): Promise<void>;
+    /**
+     * Stream with connection pooling (fast path).
+     */
+    private streamWithPooling;
+    /**
+     * Stream without connection pooling (original behavior).
+     */
+    private streamWithoutPooling;
+    /**
+     * Close the pooled WebSocket connection.
      */
-    stream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void>;
+    close(): void;
     private parseError;
 }
 /**
@@ -225,15 +261,22 @@ declare class TTSResource {
  * // List voices
  * const voices = await client.voices.list();
  *
- * // Generate audio
+ * // Generate audio with fast model (1.5B params)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-one-turbo',
+ *   model: 'kugel-1-turbo',
+ * });
+ *
+ * // Generate audio with premium model (7B params)
+ * const audio = await client.tts.generate({
+ *   text: 'Hello, world!',
+ *   model: 'kugel-1',
  * });
  * ```
  */
 declare class KugelAudio {
     private _apiKey;
+    private _isMasterKey;
     private _apiUrl;
     private _ttsUrl;
     private _timeout;
@@ -246,8 +289,15 @@ declare class KugelAudio {
     constructor(options: KugelAudioOptions);
     /** Get API key */
     get apiKey(): string;
+    /** Check if using master key authentication */
+    get isMasterKey(): boolean;
     /** Get TTS URL */
     get ttsUrl(): string;
+    /**
+     * Close the client and release resources.
+     * This closes any pooled WebSocket connections.
+     */
+    close(): void;
     /**
      * Make an HTTP request to the API.
      * @internal

package/dist/index.d.ts

@@ -47,7 +47,7 @@ interface Voice {
 interface GenerateOptions {
     /** Text to synthesize */
     text: string;
-    /** Model to use (default: 'kugel-one-turbo') */
+    /** Model to use: 'kugel-1-turbo' (1.5B, fast) or 'kugel-1' (7B, premium). Default: 'kugel-1-turbo' */
     model?: string;
     /** Voice ID to use */
     voiceId?: number;
@@ -153,6 +153,8 @@ interface StreamCallbacks {
 interface KugelAudioOptions {
     /** Your KugelAudio API key */
     apiKey: string;
+    /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
+    isMasterKey?: boolean;
     /** API base URL (default: https://api.kugelaudio.com) */
     apiUrl?: string;
     /** TTS server URL (default: https://eu.kugelaudio.com) */
@@ -200,16 +202,50 @@ declare class VoicesResource {
  */
 declare class TTSResource {
     private client;
+    private wsConnection;
+    private wsUrl;
+    private pendingRequests;
+    private requestCounter;
     constructor(client: KugelAudio);
     /**
      * Generate audio from text with streaming via WebSocket.
      * Returns complete audio after all chunks are received.
      */
     generate(options: GenerateOptions): Promise<AudioResponse>;
+    /**
+     * Build the WebSocket URL with appropriate auth param.
+     */
+    private buildWsUrl;
+    /**
+     * Get or create a WebSocket connection for connection pooling.
+     * This avoids the ~220ms connect overhead on each request.
+     */
+    private getConnection;
+    /**
+     * Setup message handler for pooled connection.
+     */
+    private setupMessageHandler;
     /**
      * Stream audio from text via WebSocket.
+     * Uses connection pooling for faster TTFA (~180ms vs ~400ms).
+     *
+     * @param options - Generation options
+     * @param callbacks - Stream callbacks
+     * @param reuseConnection - If true (default), reuse WebSocket connection
+     */
+    stream(options: GenerateOptions, callbacks: StreamCallbacks, reuseConnection?: boolean): Promise<void>;
+    /**
+     * Stream with connection pooling (fast path).
+     */
+    private streamWithPooling;
+    /**
+     * Stream without connection pooling (original behavior).
+     */
+    private streamWithoutPooling;
+    /**
+     * Close the pooled WebSocket connection.
      */
-    stream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void>;
+    close(): void;
     private parseError;
 }
 /**
@@ -225,15 +261,22 @@ declare class TTSResource {
  * // List voices
  * const voices = await client.voices.list();
  *
- * // Generate audio
+ * // Generate audio with fast model (1.5B params)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-one-turbo',
+ *   model: 'kugel-1-turbo',
+ * });
+ *
+ * // Generate audio with premium model (7B params)
+ * const audio = await client.tts.generate({
+ *   text: 'Hello, world!',
+ *   model: 'kugel-1',
  * });
  * ```
  */
 declare class KugelAudio {
     private _apiKey;
+    private _isMasterKey;
     private _apiUrl;
     private _ttsUrl;
     private _timeout;
@@ -246,8 +289,15 @@ declare class KugelAudio {
     constructor(options: KugelAudioOptions);
     /** Get API key */
     get apiKey(): string;
+    /** Check if using master key authentication */
+    get isMasterKey(): boolean;
     /** Get TTS URL */
     get ttsUrl(): string;
+    /**
+     * Close the client and release resources.
+     * This closes any pooled WebSocket connections.
+     */
+    close(): void;
     /**
      * Make an HTTP request to the API.
      * @internal

package/dist/index.js

@@ -212,6 +212,10 @@ var VoicesResource = class {
 var TTSResource = class {
   constructor(client) {
     this.client = client;
+    this.wsConnection = null;
+    this.wsUrl = null;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.requestCounter = 0;
   }
   /**
    * Generate audio from text with streaming via WebSocket.
@@ -244,19 +248,157 @@ var TTSResource = class {
       rtf: finalStats ? finalStats.rtf : 0
     };
   }
+  /**
+   * Build the WebSocket URL with appropriate auth param.
+   */
+  buildWsUrl() {
+    const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
+    const authParam = this.client.isMasterKey ? "master_key" : "api_key";
+    return `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+  }
+  /**
+   * Get or create a WebSocket connection for connection pooling.
+   * This avoids the ~220ms connect overhead on each request.
+   */
+  async getConnection() {
+    const url = this.buildWsUrl();
+    if (this.wsConnection && this.wsUrl === url && this.wsConnection.readyState === WebSocket.OPEN) {
+      return this.wsConnection;
+    }
+    if (this.wsConnection) {
+      try {
+        this.wsConnection.close();
+      } catch {
+      }
+      this.wsConnection = null;
+    }
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url);
+      ws.onopen = () => {
+        this.wsConnection = ws;
+        this.wsUrl = url;
+        this.setupMessageHandler(ws);
+        resolve(ws);
+      };
+      ws.onerror = () => {
+        reject(new KugelAudioError("WebSocket connection error"));
+      };
+    });
+  }
+  /**
+   * Setup message handler for pooled connection.
+   */
+  setupMessageHandler(ws) {
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        const [requestId, pending] = [...this.pendingRequests.entries()][0] || [];
+        if (!pending) return;
+        if (data.error) {
+          const error = this.parseError(data.error);
+          pending.callbacks.onError?.(error);
+          this.pendingRequests.delete(requestId);
+          pending.reject(error);
+          return;
+        }
+        if (data.final) {
+          const stats = {
+            final: true,
+            chunks: data.chunks,
+            totalSamples: data.total_samples,
+            durationMs: data.dur_ms,
+            generationMs: data.gen_ms,
+            ttfaMs: data.ttfa_ms,
+            rtf: data.rtf,
+            error: data.error
+          };
+          pending.callbacks.onFinal?.(stats);
+          this.pendingRequests.delete(requestId);
+          pending.resolve();
+          return;
+        }
+        if (data.audio) {
+          const chunk = {
+            audio: data.audio,
+            encoding: data.enc || "pcm_s16le",
+            index: data.idx,
+            sampleRate: data.sr,
+            samples: data.samples
+          };
+          pending.callbacks.onChunk?.(chunk);
+        }
+      } catch (e) {
+        console.error("Failed to parse WebSocket message:", e);
+      }
+    };
+    ws.onclose = (event) => {
+      this.wsConnection = null;
+      this.wsUrl = null;
+      for (const [id, pending] of this.pendingRequests) {
+        pending.callbacks.onClose?.();
+        if (event.code === 4001) {
+          pending.reject(new AuthenticationError("Authentication failed"));
+        } else if (event.code === 4003) {
+          pending.reject(new InsufficientCreditsError("Insufficient credits"));
+        }
+        this.pendingRequests.delete(id);
+      }
+    };
+    ws.onerror = () => {
+      const error = new KugelAudioError("WebSocket connection error");
+      for (const [id, pending] of this.pendingRequests) {
+        pending.callbacks.onError?.(error);
+        pending.reject(error);
+        this.pendingRequests.delete(id);
+      }
+    };
+  }
   /**
    * Stream audio from text via WebSocket.
+   * Uses connection pooling for faster TTFA (~180ms vs ~400ms).
+   *
+   * @param options - Generation options
+   * @param callbacks - Stream callbacks
+   * @param reuseConnection - If true (default), reuse WebSocket connection
+   */
+  stream(options, callbacks, reuseConnection = true) {
+    if (reuseConnection) {
+      return this.streamWithPooling(options, callbacks);
+    }
+    return this.streamWithoutPooling(options, callbacks);
+  }
+  /**
+   * Stream with connection pooling (fast path).
+   */
+  async streamWithPooling(options, callbacks) {
+    const ws = await this.getConnection();
+    const requestId = ++this.requestCounter;
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(requestId, { callbacks, resolve, reject });
+      callbacks.onOpen?.();
+      ws.send(JSON.stringify({
+        text: options.text,
+        model: options.model || "kugel-1-turbo",
+        voice_id: options.voiceId,
+        cfg_scale: options.cfgScale ?? 2,
+        max_new_tokens: options.maxNewTokens ?? 2048,
+        sample_rate: options.sampleRate ?? 24e3,
+        speaker_prefix: options.speakerPrefix ?? true
+      }));
+    });
+  }
+  /**
+   * Stream without connection pooling (original behavior).
    */
-  stream(options, callbacks) {
+  streamWithoutPooling(options, callbacks) {
     return new Promise((resolve, reject) => {
-      const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
-      const url = `${wsUrl}/ws/tts?api_key=${this.client.apiKey}`;
+      const url = this.buildWsUrl();
       const ws = new WebSocket(url);
       ws.onopen = () => {
         callbacks.onOpen?.();
         ws.send(JSON.stringify({
           text: options.text,
-          model: options.model || "kugel-one-turbo",
+          model: options.model || "kugel-1-turbo",
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
@@ -319,6 +461,19 @@ var TTSResource = class {
       };
     });
   }
+  /**
+   * Close the pooled WebSocket connection.
+   */
+  close() {
+    if (this.wsConnection) {
+      try {
+        this.wsConnection.close();
+      } catch {
+      }
+      this.wsConnection = null;
+      this.wsUrl = null;
+    }
+  }
   parseError(message) {
     const lower = message.toLowerCase();
     if (lower.includes("auth") || lower.includes("unauthorized")) {
@@ -336,6 +491,7 @@ var KugelAudio = class {
       throw new Error("API key is required");
     }
     this._apiKey = options.apiKey;
+    this._isMasterKey = options.isMasterKey || false;
     this._apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
     this._timeout = options.timeout || 6e4;
@@ -347,10 +503,21 @@ var KugelAudio = class {
   get apiKey() {
     return this._apiKey;
   }
+  /** Check if using master key authentication */
+  get isMasterKey() {
+    return this._isMasterKey;
+  }
   /** Get TTS URL */
   get ttsUrl() {
     return this._ttsUrl;
   }
+  /**
+   * Close the client and release resources.
+   * This closes any pooled WebSocket connections.
+   */
+  close() {
+    this.tts.close();
+  }
   /**
    * Make an HTTP request to the API.
    * @internal

package/dist/index.mjs

@@ -176,6 +176,10 @@ var VoicesResource = class {
 var TTSResource = class {
   constructor(client) {
     this.client = client;
+    this.wsConnection = null;
+    this.wsUrl = null;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.requestCounter = 0;
   }
   /**
    * Generate audio from text with streaming via WebSocket.
@@ -208,19 +212,157 @@ var TTSResource = class {
       rtf: finalStats ? finalStats.rtf : 0
     };
   }
+  /**
+   * Build the WebSocket URL with appropriate auth param.
+   */
+  buildWsUrl() {
+    const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
+    const authParam = this.client.isMasterKey ? "master_key" : "api_key";
+    return `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+  }
+  /**
+   * Get or create a WebSocket connection for connection pooling.
+   * This avoids the ~220ms connect overhead on each request.
+   */
+  async getConnection() {
+    const url = this.buildWsUrl();
+    if (this.wsConnection && this.wsUrl === url && this.wsConnection.readyState === WebSocket.OPEN) {
+      return this.wsConnection;
+    }
+    if (this.wsConnection) {
+      try {
+        this.wsConnection.close();
+      } catch {
+      }
+      this.wsConnection = null;
+    }
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url);
+      ws.onopen = () => {
+        this.wsConnection = ws;
+        this.wsUrl = url;
+        this.setupMessageHandler(ws);
+        resolve(ws);
+      };
+      ws.onerror = () => {
+        reject(new KugelAudioError("WebSocket connection error"));
+      };
+    });
+  }
+  /**
+   * Setup message handler for pooled connection.
+   */
+  setupMessageHandler(ws) {
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+        const [requestId, pending] = [...this.pendingRequests.entries()][0] || [];
+        if (!pending) return;
+        if (data.error) {
+          const error = this.parseError(data.error);
+          pending.callbacks.onError?.(error);
+          this.pendingRequests.delete(requestId);
+          pending.reject(error);
+          return;
+        }
+        if (data.final) {
+          const stats = {
+            final: true,
+            chunks: data.chunks,
+            totalSamples: data.total_samples,
+            durationMs: data.dur_ms,
+            generationMs: data.gen_ms,
+            ttfaMs: data.ttfa_ms,
+            rtf: data.rtf,
+            error: data.error
+          };
+          pending.callbacks.onFinal?.(stats);
+          this.pendingRequests.delete(requestId);
+          pending.resolve();
+          return;
+        }
+        if (data.audio) {
+          const chunk = {
+            audio: data.audio,
+            encoding: data.enc || "pcm_s16le",
+            index: data.idx,
+            sampleRate: data.sr,
+            samples: data.samples
+          };
+          pending.callbacks.onChunk?.(chunk);
+        }
+      } catch (e) {
+        console.error("Failed to parse WebSocket message:", e);
+      }
+    };
+    ws.onclose = (event) => {
+      this.wsConnection = null;
+      this.wsUrl = null;
+      for (const [id, pending] of this.pendingRequests) {
+        pending.callbacks.onClose?.();
+        if (event.code === 4001) {
+          pending.reject(new AuthenticationError("Authentication failed"));
+        } else if (event.code === 4003) {
+          pending.reject(new InsufficientCreditsError("Insufficient credits"));
+        }
+        this.pendingRequests.delete(id);
+      }
+    };
+    ws.onerror = () => {
+      const error = new KugelAudioError("WebSocket connection error");
+      for (const [id, pending] of this.pendingRequests) {
+        pending.callbacks.onError?.(error);
+        pending.reject(error);
+        this.pendingRequests.delete(id);
+      }
+    };
+  }
   /**
    * Stream audio from text via WebSocket.
+   * Uses connection pooling for faster TTFA (~180ms vs ~400ms).
+   *
+   * @param options - Generation options
+   * @param callbacks - Stream callbacks
+   * @param reuseConnection - If true (default), reuse WebSocket connection
+   */
+  stream(options, callbacks, reuseConnection = true) {
+    if (reuseConnection) {
+      return this.streamWithPooling(options, callbacks);
+    }
+    return this.streamWithoutPooling(options, callbacks);
+  }
+  /**
+   * Stream with connection pooling (fast path).
+   */
+  async streamWithPooling(options, callbacks) {
+    const ws = await this.getConnection();
+    const requestId = ++this.requestCounter;
+    return new Promise((resolve, reject) => {
+      this.pendingRequests.set(requestId, { callbacks, resolve, reject });
+      callbacks.onOpen?.();
+      ws.send(JSON.stringify({
+        text: options.text,
+        model: options.model || "kugel-1-turbo",
+        voice_id: options.voiceId,
+        cfg_scale: options.cfgScale ?? 2,
+        max_new_tokens: options.maxNewTokens ?? 2048,
+        sample_rate: options.sampleRate ?? 24e3,
+        speaker_prefix: options.speakerPrefix ?? true
+      }));
+    });
+  }
+  /**
+   * Stream without connection pooling (original behavior).
    */
-  stream(options, callbacks) {
+  streamWithoutPooling(options, callbacks) {
     return new Promise((resolve, reject) => {
-      const wsUrl = this.client.ttsUrl.replace("https://", "wss://").replace("http://", "ws://");
-      const url = `${wsUrl}/ws/tts?api_key=${this.client.apiKey}`;
+      const url = this.buildWsUrl();
       const ws = new WebSocket(url);
       ws.onopen = () => {
         callbacks.onOpen?.();
         ws.send(JSON.stringify({
           text: options.text,
-          model: options.model || "kugel-one-turbo",
+          model: options.model || "kugel-1-turbo",
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2,
           max_new_tokens: options.maxNewTokens ?? 2048,
@@ -283,6 +425,19 @@ var TTSResource = class {
       };
     });
   }
+  /**
+   * Close the pooled WebSocket connection.
+   */
+  close() {
+    if (this.wsConnection) {
+      try {
+        this.wsConnection.close();
+      } catch {
+      }
+      this.wsConnection = null;
+      this.wsUrl = null;
+    }
+  }
   parseError(message) {
     const lower = message.toLowerCase();
     if (lower.includes("auth") || lower.includes("unauthorized")) {
@@ -300,6 +455,7 @@ var KugelAudio = class {
       throw new Error("API key is required");
     }
     this._apiKey = options.apiKey;
+    this._isMasterKey = options.isMasterKey || false;
     this._apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/$/, "");
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, "");
     this._timeout = options.timeout || 6e4;
@@ -311,10 +467,21 @@ var KugelAudio = class {
   get apiKey() {
     return this._apiKey;
   }
+  /** Check if using master key authentication */
+  get isMasterKey() {
+    return this._isMasterKey;
+  }
   /** Get TTS URL */
   get ttsUrl() {
     return this._ttsUrl;
   }
+  /**
+   * Close the client and release resources.
+   * This closes any pooled WebSocket connections.
+   */
+  close() {
+    this.tts.close();
+  }
   /**
    * Make an HTTP request to the API.
    * @internal

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "kugelaudio",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Official JavaScript/TypeScript SDK for KugelAudio TTS API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.js"
     }
   },
   "files": [

package/src/client.ts

@@ -111,6 +111,15 @@ class VoicesResource {
  * TTS resource for text-to-speech generation.
  */
 class TTSResource {
+  private wsConnection: WebSocket | null = null;
+  private wsUrl: string | null = null;
+  private pendingRequests: Map<number, {
+    callbacks: StreamCallbacks;
+    resolve: () => void;
+    reject: (error: Error) => void;
+  }> = new Map();
+  private requestCounter = 0;
+
   constructor(private client: KugelAudio) {}
 
   /**
@@ -149,16 +158,196 @@ class TTSResource {
     };
   }
 
+  /**
+   * Build the WebSocket URL with appropriate auth param.
+   */
+  private buildWsUrl(): string {
+    const wsUrl = this.client.ttsUrl
+      .replace('https://', 'wss://')
+      .replace('http://', 'ws://');
+    // Use master_key param for master keys (bypasses billing), api_key for regular keys
+    const authParam = this.client.isMasterKey ? 'master_key' : 'api_key';
+    return `${wsUrl}/ws/tts?${authParam}=${this.client.apiKey}`;
+  }
+
+  /**
+   * Get or create a WebSocket connection for connection pooling.
+   * This avoids the ~220ms connect overhead on each request.
+   */
+  private async getConnection(): Promise<WebSocket> {
+    const url = this.buildWsUrl();
+
+    // Return existing connection if valid
+    if (
+      this.wsConnection &&
+      this.wsUrl === url &&
+      this.wsConnection.readyState === WebSocket.OPEN
+    ) {
+      return this.wsConnection;
+    }
+
+    // Close old connection if URL changed
+    if (this.wsConnection) {
+      try {
+        this.wsConnection.close();
+      } catch {
+        // Ignore close errors
+      }
+      this.wsConnection = null;
+    }
+
+    // Create new connection
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(url);
+
+      ws.onopen = () => {
+        this.wsConnection = ws;
+        this.wsUrl = url;
+        this.setupMessageHandler(ws);
+        resolve(ws);
+      };
+
+      ws.onerror = () => {
+        reject(new KugelAudioError('WebSocket connection error'));
+      };
+    });
+  }
+
+  /**
+   * Setup message handler for pooled connection.
+   */
+  private setupMessageHandler(ws: WebSocket): void {
+    ws.onmessage = (event) => {
+      try {
+        const data = JSON.parse(event.data);
+
+        // Get the current pending request (we process one at a time)
+        const [requestId, pending] = [...this.pendingRequests.entries()][0] || [];
+        if (!pending) return;
+
+        if (data.error) {
+          const error = this.parseError(data.error);
+          pending.callbacks.onError?.(error);
+          this.pendingRequests.delete(requestId);
+          pending.reject(error);
+          return;
+        }
+
+        if (data.final) {
+          const stats: GenerationStats = {
+            final: true,
+            chunks: data.chunks,
+            totalSamples: data.total_samples,
+            durationMs: data.dur_ms,
+            generationMs: data.gen_ms,
+            ttfaMs: data.ttfa_ms,
+            rtf: data.rtf,
+            error: data.error,
+          };
+          pending.callbacks.onFinal?.(stats);
+          this.pendingRequests.delete(requestId);
+          pending.resolve();
+          return;
+        }
+
+        if (data.audio) {
+          const chunk: AudioChunk = {
+            audio: data.audio,
+            encoding: data.enc || 'pcm_s16le',
+            index: data.idx,
+            sampleRate: data.sr,
+            samples: data.samples,
+          };
+          pending.callbacks.onChunk?.(chunk);
+        }
+      } catch (e) {
+        console.error('Failed to parse WebSocket message:', e);
+      }
+    };
+
+    ws.onclose = (event) => {
+      // Clear connection pool
+      this.wsConnection = null;
+      this.wsUrl = null;
+
+      // Reject all pending requests
+      for (const [id, pending] of this.pendingRequests) {
+        pending.callbacks.onClose?.();
+        if (event.code === 4001) {
+          pending.reject(new AuthenticationError('Authentication failed'));
+        } else if (event.code === 4003) {
+          pending.reject(new InsufficientCreditsError('Insufficient credits'));
+        }
+        this.pendingRequests.delete(id);
+      }
+    };
+
+    ws.onerror = () => {
+      // Reject all pending requests
+      const error = new KugelAudioError('WebSocket connection error');
+      for (const [id, pending] of this.pendingRequests) {
+        pending.callbacks.onError?.(error);
+        pending.reject(error);
+        this.pendingRequests.delete(id);
+      }
+    };
+  }
+
   /**
    * Stream audio from text via WebSocket.
+   * Uses connection pooling for faster TTFA (~180ms vs ~400ms).
+   *
+   * @param options - Generation options
+   * @param callbacks - Stream callbacks
+   * @param reuseConnection - If true (default), reuse WebSocket connection
+   */
+  stream(
+    options: GenerateOptions,
+    callbacks: StreamCallbacks,
+    reuseConnection = true
+  ): Promise<void> {
+    if (reuseConnection) {
+      return this.streamWithPooling(options, callbacks);
+    }
+    return this.streamWithoutPooling(options, callbacks);
+  }
+
+  /**
+   * Stream with connection pooling (fast path).
    */
-  stream(options: GenerateOptions, callbacks: StreamCallbacks): Promise<void> {
+  private async streamWithPooling(
+    options: GenerateOptions,
+    callbacks: StreamCallbacks
+  ): Promise<void> {
+    const ws = await this.getConnection();
+    const requestId = ++this.requestCounter;
+
     return new Promise((resolve, reject) => {
-      const wsUrl = this.client.ttsUrl
-        .replace('https://', 'wss://')
-        .replace('http://', 'ws://');
-      const url = `${wsUrl}/ws/tts?api_key=${this.client.apiKey}`;
+      this.pendingRequests.set(requestId, { callbacks, resolve, reject });
+
+      callbacks.onOpen?.();
+
+      ws.send(JSON.stringify({
+        text: options.text,
+        model: options.model || 'kugel-1-turbo',
+        voice_id: options.voiceId,
+        cfg_scale: options.cfgScale ?? 2.0,
+        max_new_tokens: options.maxNewTokens ?? 2048,
+        sample_rate: options.sampleRate ?? 24000,
+        speaker_prefix: options.speakerPrefix ?? true,
+      }));
+    });
+  }
 
+  /**
+   * Stream without connection pooling (original behavior).
+   */
+  private streamWithoutPooling(
+    options: GenerateOptions,
+    callbacks: StreamCallbacks
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const url = this.buildWsUrl();
       const ws = new WebSocket(url);
 
       ws.onopen = () => {
@@ -166,7 +355,7 @@ class TTSResource {
         // Send TTS request
         ws.send(JSON.stringify({
           text: options.text,
-          model: options.model || 'kugel-one-turbo',
+          model: options.model || 'kugel-1-turbo',
           voice_id: options.voiceId,
           cfg_scale: options.cfgScale ?? 2.0,
           max_new_tokens: options.maxNewTokens ?? 2048,
@@ -236,6 +425,21 @@ class TTSResource {
     });
   }
 
+  /**
+   * Close the pooled WebSocket connection.
+   */
+  close(): void {
+    if (this.wsConnection) {
+      try {
+        this.wsConnection.close();
+      } catch {
+        // Ignore close errors
+      }
+      this.wsConnection = null;
+      this.wsUrl = null;
+    }
+  }
+
   private parseError(message: string): Error {
     const lower = message.toLowerCase();
     if (lower.includes('auth') || lower.includes('unauthorized')) {
@@ -261,15 +465,22 @@ class TTSResource {
  * // List voices
  * const voices = await client.voices.list();
  *
- * // Generate audio
+ * // Generate audio with fast model (1.5B params)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-one-turbo',
+ *   model: 'kugel-1-turbo',
+ * });
+ *
+ * // Generate audio with premium model (7B params)
+ * const audio = await client.tts.generate({
+ *   text: 'Hello, world!',
+ *   model: 'kugel-1',
  * });
  * ```
  */
 export class KugelAudio {
   private _apiKey: string;
+  private _isMasterKey: boolean;
   private _apiUrl: string;
   private _ttsUrl: string;
   private _timeout: number;
@@ -287,6 +498,7 @@ export class KugelAudio {
     }
 
     this._apiKey = options.apiKey;
+    this._isMasterKey = options.isMasterKey || false;
     this._apiUrl = (options.apiUrl || DEFAULT_API_URL).replace(/\/$/, '');
     // If ttsUrl not specified, use apiUrl (backend proxies to TTS server)
     this._ttsUrl = (options.ttsUrl || this._apiUrl).replace(/\/$/, '');
@@ -302,11 +514,24 @@ export class KugelAudio {
     return this._apiKey;
   }
 
+  /** Check if using master key authentication */
+  get isMasterKey(): boolean {
+    return this._isMasterKey;
+  }
+
   /** Get TTS URL */
   get ttsUrl(): string {
     return this._ttsUrl;
   }
 
+  /**
+   * Close the client and release resources.
+   * This closes any pooled WebSocket connections.
+   */
+  close(): void {
+    this.tts.close();
+  }
+
   /**
    * Make an HTTP request to the API.
    * @internal

package/src/index.ts

@@ -18,13 +18,13 @@
  * // Generate audio (non-streaming)
  * const audio = await client.tts.generate({
  *   text: 'Hello, world!',
- *   model: 'kugel-one-turbo',
+ *   model: 'kugel-1-turbo',
  *   voiceId: 123,
  * });
  *
  * // Generate audio (streaming)
  * await client.tts.stream(
- *   { text: 'Hello, world!', model: 'kugel-one-turbo' },
+ *   { text: 'Hello, world!', model: 'kugel-1-turbo' },
  *   {
  *     onChunk: (chunk) => {
  *       // Process audio chunk

package/src/types.ts

@@ -53,7 +53,7 @@ export interface Voice {
 export interface GenerateOptions {
   /** Text to synthesize */
   text: string;
-  /** Model to use (default: 'kugel-one-turbo') */
+  /** Model to use: 'kugel-1-turbo' (1.5B, fast) or 'kugel-1' (7B, premium). Default: 'kugel-1-turbo' */
   model?: string;
   /** Voice ID to use */
   voiceId?: number;
@@ -165,6 +165,8 @@ export interface StreamCallbacks {
 export interface KugelAudioOptions {
   /** Your KugelAudio API key */
   apiKey: string;
+  /** Whether apiKey is a master key (for internal/server-side use). Master keys bypass billing. */
+  isMasterKey?: boolean;
   /** API base URL (default: https://api.kugelaudio.com) */
   apiUrl?: string;
   /** TTS server URL (default: https://eu.kugelaudio.com) */