---

name: elevenlabs-sdk-patterns description: | Apply production-ready ElevenLabs SDK patterns for TypeScript and Python. Use when implementing ElevenLabs integrations, refactoring SDK usage, or establishing team coding standards for audio AI applications. Trigger with "elevenlabs SDK patterns", "elevenlabs best practices", "elevenlabs code patterns", "idiomatic elevenlabs", "elevenlabs typescript". allowed-tools: Read, Write, Edit version: 1.6.0 license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• voice
• ai
• elevenlabs
• sdk
• patterns compatibility: Designed for Claude Code

---

ElevenLabs SDK Patterns

Overview

Production-ready patterns for the ElevenLabs TypeScript and Python SDKs. Covers singleton clients, type-safe TTS wrappers, error classification, retry with a concurrency queue, and multi-tenant client factories. Adopt them incrementally — the singleton client alone fixes the most common mistakes; add error classification and the queue as throughput grows.

The full, copy-ready code for all six patterns lives in references/implementation.md. This file gives the high-level workflow plus the essential skeleton so you can follow it end to end, then drill into the reference for depth.

Prerequisites

• @elevenlabs/elevenlabs-js installed (TypeScript) or elevenlabs (Python)
• ELEVENLABS_API_KEY exported in the environment (never hardcode the key)
• Familiarity with async/await patterns and error handling best practices

Instructions

Apply the patterns in order — each builds on the previous one:

1. Singleton client. Create one lazily-initialized ElevenLabsClient guarded by an ELEVENLABS_API_KEY check so misconfiguration fails fast at startup. Expose a resetClient() for tests. This is the skeleton every other pattern imports:

   let instance: ElevenLabsClient | null = null;
   export function getClient(): ElevenLabsClient {
     if (!instance) {
       if (!process.env.ELEVENLABS_API_KEY) {
         throw new Error("ELEVENLABS_API_KEY environment variable is required");
       }
       instance = new ElevenLabsClient({
         apiKey: process.env.ELEVENLABS_API_KEY,
         maxRetries: 3,
         timeoutInSeconds: 60,
       });
     }
     return instance;
   }
   

2. Type-safe TTS service. Wrap textToSpeech.convert behind a typed TTSOptions interface and named VoicePreset records (narration / conversational / dramatic / neutral) so voice settings are compile-time checked and consistent across the codebase.

3. Error classification. Map raw SDK errors to an ElevenLabsServiceError carrying a stable code (auth_failed, quota_exceeded, rate_limited, concurrent_limit, voice_not_found, invalid_request, server_error, network_error) and a retryable flag driven by HTTP status.

4. Retry with a concurrency queue. Route calls through a p-queue sized to your plan's concurrent-request limit, retrying only retryable errors with exponential backoff + jitter.

5. Multi-tenant factory. For SaaS platforms, key one client per tenant in a Map so each customer's API key stays isolated.

6. Python async. Mirror the singleton + streaming-to-file pattern with AsyncElevenLabsClient for non-blocking Python backends.

See references/implementation.md for the complete code for every step above.

Output

Applying these patterns produces a small set of focused SDK modules in the target project:

• src/elevenlabs/client.ts — singleton client with config + resetClient()
• src/elevenlabs/tts-service.ts — typed generateSpeech() / generateToFile() with voice presets
• src/elevenlabs/errors.ts — ElevenLabsServiceError + classifyError()
• src/elevenlabs/queue.ts — queuedRequest() with backoff and plan-aware concurrency
• src/elevenlabs/multi-tenant.ts — per-tenant client factory (SaaS only)
• elevenlabs_service.py — async singleton + streaming generator (Python backends)

TTS calls return an audio stream you pipe to a file or HTTP response; mp3_44100_128 is the default output format.

Error Handling

Pattern	Error Type	Benefit
classifyError()	All API errors	Maps HTTP status to actionable codes
queuedRequest()	429, 5xx	Auto-retry with exponential backoff + jitter
Singleton guard	Missing env var	Fails fast at startup, not at first call

Only retryable codes (rate_limited, concurrent_limit, server_error, network_error) are retried; auth_failed, quota_exceeded, voice_not_found, and invalid_request throw immediately so callers surface a real problem instead of looping.

Examples

Generate speech to a file (TypeScript):

import { generateToFile } from "./elevenlabs/tts-service";

await generateToFile(
  { voiceId: "21m00Tcm4TlvDq8ikWAM", text: "Welcome aboard.", preset: "narration" },
  "welcome.mp3"
);

Wrap a call in the retry queue:

import { queuedRequest } from "./elevenlabs/queue";
import { generateSpeech } from "./elevenlabs/tts-service";

const audio = await queuedRequest(() =>
  generateSpeech({ voiceId: "21m00Tcm4TlvDq8ikWAM", text: "High-throughput job." })
);

Full runnable examples — including the Python async path and multi-tenant usage — are in references/implementation.md.

Resources

• ElevenLabs JS SDK Source
• ElevenLabs Python SDK
• p-queue (Concurrency)
• Full implementation walkthrough

Next Steps

Apply these patterns in elevenlabs-core-workflow-a for TTS generation, or see elevenlabs-rate-limits for advanced throttling and plan-aware concurrency tuning.