feat: add key pool rotation to all 5 ElevenLabs providers

jddunn · jddunn · commit fa38ec523b6b · 2026-04-10T02:27:45.000-07:00
diff --git a/src/media/audio/providers/ElevenLabsSFXProvider.ts b/src/media/audio/providers/ElevenLabsSFXProvider.ts
@@ -21,6 +21,8 @@
 
 import type { IAudioGenerator } from '../IAudioGenerator.js';
 import type { MusicGenerateRequest, SFXGenerateRequest, AudioResult } from '../types.js';
+import { ApiKeyPool } from '../../../core/providers/ApiKeyPool.js';
+import { isQuotaError } from '../../../core/providers/quotaErrors.js';
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -85,6 +87,9 @@ export class ElevenLabsSFXProvider implements IAudioGenerator {
   /** Internal resolved configuration. */
   private _config!: Required<Pick<ElevenLabsSFXProviderConfig, 'apiKey' | 'baseURL'>>;
 
+  /** API key pool for round-robin rotation and quota failover. */
+  private keyPool!: ApiKeyPool;
+
   // -------------------------------------------------------------------------
   // Lifecycle
   // -------------------------------------------------------------------------
@@ -108,6 +113,7 @@ export class ElevenLabsSFXProvider implements IAudioGenerator {
           ? config.baseURL.trim()
           : 'https://api.elevenlabs.io/v1',
     };
+    this.keyPool = new ApiKeyPool(apiKey);
 
     this.isInitialized = true;
   }
@@ -150,14 +156,28 @@ export class ElevenLabsSFXProvider implements IAudioGenerator {
 
     if (request.durationSec !== undefined) body.duration_seconds = request.durationSec;
 
-    const response = await fetch(url, {
-      method: 'POST',
-      headers: {
-        'xi-api-key': this._config.apiKey,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(body),
-    });
+    const doFetch = (key: string) =>
+      fetch(url, {
+        method: 'POST',
+        headers: {
+          'xi-api-key': key,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      });
+
+    const key = this.keyPool.next();
+    let response = await doFetch(key);
+
+    if (!response.ok && this.keyPool.size > 1) {
+      const errBody = await response.text().catch(() => '');
+      if (isQuotaError(response.status, errBody)) {
+        this.keyPool.markExhausted(key);
+        response = await doFetch(this.keyPool.next());
+      } else {
+        throw new Error(`ElevenLabs SFX generation failed (${response.status}): ${errBody}`);
+      }
+    }
 
     if (!response.ok) {
       const errorText = await response.text();
diff --git a/src/speech/providers/ElevenLabsTextToSpeechProvider.ts b/src/speech/providers/ElevenLabsTextToSpeechProvider.ts
@@ -4,6 +4,8 @@ import type {
   SpeechVoice,
   TextToSpeechProvider,
 } from '../types.js';
+import { ApiKeyPool } from '../../core/providers/ApiKeyPool.js';
+import { isQuotaError } from '../../core/providers/quotaErrors.js';
 
 /**
  * Configuration for the {@link ElevenLabsTextToSpeechProvider}.
@@ -108,6 +110,9 @@ export class ElevenLabsTextToSpeechProvider implements TextToSpeechProvider {
   /** Fetch implementation — injected for testability, defaults to global fetch. */
   private readonly fetchImpl: typeof fetch;
 
+  /** API key pool for round-robin rotation and quota failover. */
+  private readonly keyPool: ApiKeyPool;
+
   /**
    * Creates a new ElevenLabsTextToSpeechProvider.
    *
@@ -124,6 +129,7 @@ export class ElevenLabsTextToSpeechProvider implements TextToSpeechProvider {
    */
   constructor(private readonly config: ElevenLabsTextToSpeechProviderConfig) {
     this.fetchImpl = config.fetchImpl ?? fetch;
+    this.keyPool = new ApiKeyPool(config.apiKey);
   }
 
   /**
@@ -180,45 +186,53 @@ export class ElevenLabsTextToSpeechProvider implements TextToSpeechProvider {
 
     const model = options.model ?? this.config.model ?? 'eleven_multilingual_v2';
 
-    const response = await this.fetchImpl(
-      `${this.config.baseUrl ?? 'https://api.elevenlabs.io/v1'}/text-to-speech/${voiceId}`,
-      {
+    const baseUrl = this.config.baseUrl ?? 'https://api.elevenlabs.io/v1';
+    const requestBody = JSON.stringify({
+      text,
+      model_id: model,
+      voice_settings: {
+        stability:
+          typeof options.providerSpecificOptions?.stability === 'number'
+            ? options.providerSpecificOptions.stability
+            : 0.5,
+        similarity_boost:
+          typeof options.providerSpecificOptions?.similarityBoost === 'number'
+            ? options.providerSpecificOptions.similarityBoost
+            : 0.75,
+        style:
+          typeof options.providerSpecificOptions?.style === 'number'
+            ? options.providerSpecificOptions.style
+            : undefined,
+        use_speaker_boost:
+          typeof options.providerSpecificOptions?.useSpeakerBoost === 'boolean'
+            ? options.providerSpecificOptions.useSpeakerBoost
+            : true,
+      },
+    });
+
+    const doFetch = (key: string) =>
+      this.fetchImpl(`${baseUrl}/text-to-speech/${voiceId}`, {
         method: 'POST',
         headers: {
-          // ElevenLabs uses its own header format instead of standard Authorization
-          'xi-api-key': this.config.apiKey,
+          'xi-api-key': key,
           'Content-Type': 'application/json',
-          // Request MP3 format in the response
           Accept: 'audio/mpeg',
         },
-        body: JSON.stringify({
-          text,
-          model_id: model,
-          voice_settings: {
-            // Extract provider-specific settings with sensible defaults.
-            // These defaults produce natural-sounding output for most voices.
-            stability:
-              typeof options.providerSpecificOptions?.stability === 'number'
-                ? options.providerSpecificOptions.stability
-                : 0.5,
-            similarity_boost:
-              typeof options.providerSpecificOptions?.similarityBoost === 'number'
-                ? options.providerSpecificOptions.similarityBoost
-                : 0.75,
-            // Style is only meaningful for v2+ models; omit if not specified
-            style:
-              typeof options.providerSpecificOptions?.style === 'number'
-                ? options.providerSpecificOptions.style
-                : undefined,
-            // Speaker boost enhances vocal clarity and similarity
-            use_speaker_boost:
-              typeof options.providerSpecificOptions?.useSpeakerBoost === 'boolean'
-                ? options.providerSpecificOptions.useSpeakerBoost
-                : true,
-          },
-        }),
+        body: requestBody,
+      });
+
+    const key = this.keyPool.next();
+    let response = await doFetch(key);
+
+    if (!response.ok && this.keyPool.size > 1) {
+      const errBody = await response.text().catch(() => '');
+      if (isQuotaError(response.status, errBody)) {
+        this.keyPool.markExhausted(key);
+        response = await doFetch(this.keyPool.next());
+      } else {
+        throw new Error(`ElevenLabs synthesis failed (${response.status}): ${errBody}`);
       }
-    );
+    }
 
     if (!response.ok) {
       const message = await response.text();
diff --git a/src/voice-pipeline/providers/ElevenLabsBatchTTS.ts b/src/voice-pipeline/providers/ElevenLabsBatchTTS.ts
@@ -6,6 +6,8 @@
  */
 
 import type { IBatchTTS, BatchTTSConfig, BatchTTSResult } from '../types.js';
+import { ApiKeyPool } from '../../core/providers/ApiKeyPool.js';
+import { isQuotaError } from '../../core/providers/quotaErrors.js';
 
 /** Configuration for the ElevenLabs batch TTS provider. */
 export interface ElevenLabsBatchTTSConfig {
@@ -31,8 +33,8 @@ const BYTES_PER_SEC_MP3 = 16_000;
 export class ElevenLabsBatchTTS implements IBatchTTS {
   readonly providerId = 'elevenlabs-batch';
 
-  /** ElevenLabs API key used for authentication. */
-  private readonly apiKey: string;
+  /** API key pool for round-robin rotation and quota failover. */
+  private readonly keyPool: ApiKeyPool;
 
   /** Default voice ID when none is provided in the synthesis config. */
   private readonly defaultVoiceId: string;
@@ -44,7 +46,7 @@ export class ElevenLabsBatchTTS implements IBatchTTS {
   private readonly baseUrl: string;
 
   constructor(config: ElevenLabsBatchTTSConfig) {
-    this.apiKey = config.apiKey;
+    this.keyPool = new ApiKeyPool(config.apiKey);
     this.defaultVoiceId = config.voiceId ?? 'EXAVITQu4vr4xnSDxMaL';
     this.model = config.model ?? 'eleven_multilingual_v2';
     this.baseUrl = config.baseUrl ?? 'https://api.elevenlabs.io/v1';
@@ -62,24 +64,38 @@ export class ElevenLabsBatchTTS implements IBatchTTS {
     const voiceId = config?.voice ?? this.defaultVoiceId;
     const opts = config?.providerOptions ?? {};
 
-    const res = await fetch(`${this.baseUrl}/text-to-speech/${voiceId}`, {
-      method: 'POST',
-      headers: {
-        'xi-api-key': this.apiKey,
-        'Content-Type': 'application/json',
-        Accept: 'audio/mpeg',
-      },
-      body: JSON.stringify({
-        text,
-        model_id: config?.model ?? this.model,
-        voice_settings: {
-          stability: (opts.stability as number) ?? 0.5,
-          similarity_boost: (opts.similarityBoost as number) ?? 0.75,
-          style: (opts.style as number) ?? 0.0,
-          use_speaker_boost: (opts.useSpeakerBoost as boolean) ?? true,
+    const doFetch = (key: string) =>
+      fetch(`${this.baseUrl}/text-to-speech/${voiceId}`, {
+        method: 'POST',
+        headers: {
+          'xi-api-key': key,
+          'Content-Type': 'application/json',
+          Accept: 'audio/mpeg',
         },
-      }),
-    });
+        body: JSON.stringify({
+          text,
+          model_id: config?.model ?? this.model,
+          voice_settings: {
+            stability: (opts.stability as number) ?? 0.5,
+            similarity_boost: (opts.similarityBoost as number) ?? 0.75,
+            style: (opts.style as number) ?? 0.0,
+            use_speaker_boost: (opts.useSpeakerBoost as boolean) ?? true,
+          },
+        }),
+      });
+
+    const key = this.keyPool.next();
+    let res = await doFetch(key);
+
+    if (!res.ok && this.keyPool.size > 1) {
+      const body = await res.text().catch(() => '');
+      if (isQuotaError(res.status, body)) {
+        this.keyPool.markExhausted(key);
+        res = await doFetch(this.keyPool.next());
+      } else {
+        throw new Error(`ElevenLabs TTS failed: ${res.status} ${body.slice(0, 200)}`);
+      }
+    }
 
     if (!res.ok) {
       const detail = await res.text().catch(() => '');
diff --git a/src/voice-pipeline/providers/ElevenLabsStreamingSTT.ts b/src/voice-pipeline/providers/ElevenLabsStreamingSTT.ts
@@ -33,6 +33,7 @@ import type {
   TranscriptEvent,
   TranscriptWord,
 } from '../types.js';
+import { ApiKeyPool } from '../../core/providers/ApiKeyPool.js';
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -335,14 +336,19 @@ class ElevenLabsChunkedSTTSession extends EventEmitter implements StreamingSTTSe
 export class ElevenLabsStreamingSTT implements IStreamingSTT {
   readonly providerId = 'elevenlabs-streaming-stt';
   readonly isStreaming = true;
+  private readonly keyPool: ApiKeyPool;
 
-  constructor(private readonly config: ElevenLabsStreamingSTTConfig) {}
+  constructor(private readonly config: ElevenLabsStreamingSTTConfig) {
+    this.keyPool = new ApiKeyPool(config.apiKey);
+  }
 
   /**
    * Create a new STT session. Uses chunked REST calls to ElevenLabs'
    * batch STT endpoint for near-realtime transcription.
+   * Each session gets a fresh key from the round-robin pool.
    */
   async startSession(config?: StreamingSTTConfig): Promise<StreamingSTTSession> {
-    return new ElevenLabsChunkedSTTSession(this.config, config ?? {});
+    const resolvedConfig = { ...this.config, apiKey: this.keyPool.next() };
+    return new ElevenLabsChunkedSTTSession(resolvedConfig, config ?? {});
   }
 }
diff --git a/src/voice-pipeline/providers/ElevenLabsStreamingTTS.ts b/src/voice-pipeline/providers/ElevenLabsStreamingTTS.ts
@@ -30,6 +30,7 @@ import type {
   StreamingTTSConfig,
   EncodedAudioChunk,
 } from '../types.js';
+import { ApiKeyPool } from '../../core/providers/ApiKeyPool.js';
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -315,15 +316,20 @@ class ElevenLabsStreamingTTSSession extends EventEmitter implements StreamingTTS
  */
 export class ElevenLabsStreamingTTS implements IStreamingTTS {
   readonly providerId = 'elevenlabs-streaming';
+  private readonly keyPool: ApiKeyPool;
 
-  constructor(private readonly config: ElevenLabsStreamingTTSConfig) {}
+  constructor(private readonly config: ElevenLabsStreamingTTSConfig) {
+    this.keyPool = new ApiKeyPool(config.apiKey);
+  }
 
   /**
    * Create a new streaming TTS session connected to ElevenLabs.
    * The session opens a WebSocket and is ready to receive text tokens.
+   * Each session gets a fresh key from the round-robin pool.
    */
   async startSession(config?: StreamingTTSConfig): Promise<StreamingTTSSession> {
-    const session = new ElevenLabsStreamingTTSSession(this.config, config ?? {});
+    const resolvedConfig = { ...this.config, apiKey: this.keyPool.next() };
+    const session = new ElevenLabsStreamingTTSSession(resolvedConfig, config ?? {});
     await session.connect();
     return session;
   }
