Skip to main content 首页 创作者 comeonoliver skillshub elevenlabs-sdk-patterns
elevenlabs-sdk-patterns 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: "elevenlabs SDK patterns", "elevenlabs best practices",
"elevenlabs code patterns", "idiomatic elevenlabs", "elevenlabs typescript".
跳到安装 Skills Marketplace 发现并探索由社区构建的 Agent Skills
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ComeOnOliver/skillshub --skill elevenlabs-sdk-patterns命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
下载 Zip 下载中... 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: "elevenlabs SDK patterns", "elevenlabs best practices",
"elevenlabs code patterns", "idiomatic elevenlabs", "elevenlabs typescript".
allowed-tools Read, Write, Edit version 1.0.0 license MIT author Jeremy Longshore <jeremy@intentsolutions.io> tags ["saas","voice","ai","elevenlabs","sdk","patterns"] compatible-with claude-code
ElevenLabs SDK Patterns
Overview
Production-ready patterns for the ElevenLabs TypeScript and Python SDKs. Covers singleton clients, type-safe wrappers, error handling, retry logic, and multi-tenant patterns.
Prerequisites
@elevenlabs/elevenlabs-js installed (TypeScript) or elevenlabs (Python)Familiarity with async/await patterns
Understanding of error handling best practices
Instructions
Pattern 1: Singleton Client with Config
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js" ;
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;
}
export function resetClient
void
null
Pattern 2: Type-Safe TTS Service
import { getClient } from "./client" ;
import { Readable } from "stream" ;
import { pipeline } from "stream/promises" ;
import { createWriteStream } from "fs" ;
export type VoicePreset = "narration" | "conversational" | "dramatic" | "neutral" ;
const VOICE_PRESETS : Record <VoicePreset , {
stability : number ;
similarity_boost : number ;
style : number ;
}> = {
narration : { stability : 0.6 , similarity_boost : 0.75 , style : 0.0 },
conversational : { stability : 0.4 , similarity_boost : 0.6 , style : 0.3 },
dramatic : { stability : 0.3 , similarity_boost : 0.8 , style : 0.7 },
neutral : { stability : 0.8 , similarity_boost : 0.5 , style : 0.0 },
};
export interface TTSOptions {
voiceId : string ;
text : string ;
modelId ?: "eleven_v3" | "eleven_multilingual_v2" | "eleven_flash_v2_5" | "eleven_turbo_v2_5" ;
preset ?: VoicePreset ;
outputFormat ?: string ;
languageCode ?: string ;
}
export async function generateSpeech (options : TTSOptions Promise <ReadableStream > {
const client = getClient ();
const settings = VOICE_PRESETS [options.preset || "narration" ];
return client.textToSpeech .convert (options.voiceId , {
text : options.text ,
model_id : options.modelId || "eleven_multilingual_v2" ,
voice_settings : settings,
output_format : options.outputFormat || "mp3_44100_128" ,
language_code : options.languageCode ,
});
}
export async function generateToFile (options : TTSOptions , outputPath : string Promise <void > {
const audio = await generateSpeech (options);
await pipeline (
Readable .fromWeb (audio as any ),
createWriteStream (outputPath)
);
}
Pattern 3: Error Classification
export type ElevenLabsErrorCode =
| "auth_failed"
| "quota_exceeded"
| "rate_limited"
| "concurrent_limit"
| "voice_not_found"
| "invalid_request"
| "server_error"
| "network_error" ;
export class ElevenLabsServiceError extends Error {
constructor (
message : string ,
public readonly code : ElevenLabsErrorCode ,
public readonly httpStatus : number | null ,
public readonly retryable : boolean ,
public readonly originalError ?: Error
) {
super (message);
this .name = "ElevenLabsServiceError" ;
}
}
export function classifyError (error : unknown ElevenLabsServiceError {
if (error instanceof Error ) {
const status = (error as any ).statusCode || (error as any ).status ;
if (status === 401 ) {
const msg = (error as any ).body ?.detail ?.message || error.message ;
if (msg?.includes ("quota" )) {
return new ElevenLabsServiceError (msg, "quota_exceeded" , 401 , false , error);
}
return new ElevenLabsServiceError (msg, "auth_failed" , 401 , false , error);
}
if (status === 429 ) {
const msg = (error as any ).body ?.detail ?.message || error.message ;
const code = msg?.includes ("concurrent" ) ? "concurrent_limit" : "rate_limited" ;
return new ElevenLabsServiceError (msg, code, 429 , true , error);
}
if (status === 404 ) {
return new ElevenLabsServiceError (error.message , "voice_not_found" , 404 , false , error);
}
if (status === 400 ) {
return new ElevenLabsServiceError (error.message , "invalid_request" , 400 , false , error);
}
if (status >= 500 ) {
return new ElevenLabsServiceError (error.message , "server_error" , status, true , error);
}
return new ElevenLabsServiceError (error.message , "network_error" , null , true , error);
}
return new ElevenLabsServiceError (String (error), "network_error" , null , true );
}
Pattern 4: Retry with Concurrency Queue
import PQueue from "p-queue" ;
import { classifyError, ElevenLabsServiceError } from "./errors" ;
const queue = new PQueue ({
concurrency : 5 ,
interval : 1000 ,
intervalCap : 10 ,
});
export async function queuedRequest<T>(
operation : () => Promise <T>,
maxRetries = 3
): Promise <T> {
return queue.add (async () => {
let lastError : ElevenLabsServiceError | undefined ;
for (let attempt = 0 ; attempt < maxRetries; attempt++) {
try {
return await operation ();
} catch (err) {
lastError = classifyError (err);
if (!lastError.retryable ) throw lastError;
const delay = Math .min (1000 * Math .pow (2 , attempt), 30000 );
const jitter = Math .random () * 500 ;
await new Promise (r =>setTimeout (r, delay + jitter));
}
}
throw lastError;
}) as Promise <T>;
}
Pattern 5: Multi-Tenant Client Factory
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js" ;
const clients = new Map <string , ElevenLabsClient >();
export function getClientForTenant (tenantId : string , apiKey : string ElevenLabsClient {
if (!clients.has (tenantId)) {
clients.set (tenantId, new ElevenLabsClient ({
apiKey,
maxRetries : 3 ,
}));
}
return clients.get (tenantId)!;
}
export function removeTenantClient (tenantId : string void {
clients.delete (tenantId);
}
Pattern 6: Python Async Pattern
import os
import asyncio
from elevenlabs.client import AsyncElevenLabsClient
_client: AsyncElevenLabsClient | None = None
def get_async_client () -> AsyncElevenLabsClient:
global _client
if _client is None :
_client = AsyncElevenLabsClient(
api_key=os.environ["ELEVENLABS_API_KEY" ]
)
return _client
async def generate_speech (text: str , voice_id: str , output_path: str ):
client = get_async_client()
audio = await client.text_to_speech.convert(
voice_id=voice_id,
text=text,
model_id="eleven_multilingual_v2" ,
voice_settings={
"stability" : 0.5 ,
"similarity_boost" : 0.75 ,
},
)
with open (output_path, "wb" ) as f:
async for chunk in audio:
f.write(chunk)
asyncio.run(generate_speech("Hello!" , "21m00Tcm4TlvDq8ikWAM" , "out.mp3" ))
Pattern Summary Pattern Use Case Key Benefit Singleton client Single-tenant apps Memory efficiency, shared retries Type-safe TTS All TTS work Voice presets, compile-time checks Error classification Production error handling Actionable error codes Concurrency queue High-throughput apps Respects plan limits automatically Multi-tenant factory SaaS platforms Per-customer isolation Python async Python backends Non-blocking I/O
Error Handling Pattern Error Type Benefit classifyError()All API errors Maps HTTP to actionable codes queuedRequest()429, 5xx Auto-retry with exponential backoff Singleton guard Missing env var Fails fast at startup, not at first call
Resources
Next Steps Apply patterns in elevenlabs-core-workflow-a for TTS, or see elevenlabs-rate-limits for advanced throttling.
