ElevenLabs Reference Architecture

Overview

Production-ready architecture for ElevenLabs TTS/voice applications. Covers project

layout, service layers, caching, streaming, and multi-model orchestration. The full

code for each layer lives in references/ so this file stays a navigable map; drill

into a reference file when you need the exact implementation.

Prerequisites

• Understanding of layered architecture patterns
• ElevenLabs SDK knowledge (see elevenlabs-sdk-patterns)
• TypeScript project with async patterns
• Redis (optional, for distributed caching)
• Auth: an ElevenLabs API key exported as ELEVENLABSAPIKEY (read by the

config layer). This is the only ElevenLabs credential — your app's own request

auth (middleware/auth.ts) is separate and unrelated.

Instructions

Build the service in six layers. Each step below is the high-level move; the

verbatim code and diagrams are in the linked reference files.

Step 1: Lay out the project

Split the codebase into elevenlabs/ (client, config, models, errors, types),

services/ (tts, voice, audio, cache), api/ (routes + middleware), queue/, and

monitoring/. See the full project tree.

Step 2: Configuration layer

Define an environment-aware ElevenLabsConfig — dev uses the cheap/fast

elevenflashv25 and small output format; production uses elevenmultilingual_v2

at higher quality, more concurrency, and a larger cache. loadConfig() merges the

per-environment defaults with ELEVENLABSAPIKEY. Full interface and ENV_CONFIGS:

implementation walkthrough.

Step 3: TTS service layer

Wrap the SDK client in a TTSService that owns a singleton client and a p-queue

sized to maxConcurrency (this is what prevents 429s). generate() supports both

streaming and buffered convert, logs latency, and routes errors through

classifyError. generateLongText() splits on sentence boundaries under the 5000-char

limit to preserve prosody. Full class:

implementation walkthrough.

Step 4: Voice management service

A VoiceService over the client for list/clone/get-settings/update-settings/delete,

with category filtering (premade / cloned / generated). Full class:

implementation walkthrough.

Step 5: Wire the data flow

Requests flow Client → API layer →

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)
• ELEVENLABSAPIKEY 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

ELEVENLABSAPIKEY 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;
   }

1. 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.

1. Error classification. Map raw SDK errors to an ElevenLabsServiceError carrying a stable

code (authfailed, quotaexceeded, ratelimited, concurrentlimit, voicenotfound,

invalidrequest, servererror, network_error) and a retryable flag driven by HTTP status.

1. 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.

1. Multi-tenant factory. For Saa

ElevenLabs Security Basics

Overview

Security best practices for ElevenLabs API key management, webhook HMAC

signature verification, and protecting cloned voice data. ElevenLabs uses a

single API key (xi-api-key) and HMAC webhook authentication.

This SKILL.md carries the workflow at a high level with the essential

skeletons. Full production code for each step lives in

references/implementation.md, and end-to-end

scenarios live in references/examples.md.

Prerequisites

• ElevenLabs SDK installed
• Understanding of environment variables
• Access to ElevenLabs dashboard (Settings > API Keys)

Instructions

Step 1: API Key Management

Keep keys out of source, and add a hook that blocks accidental commits:

# .env (NEVER commit to git)
ELEVENLABS_API_KEY=sk_your_key_here

# .gitignore — MUST include these
.env
.env.local
.env.*.local

#!/bin/bash
# .git/hooks/pre-commit — reject staged ElevenLabs keys
if git diff --cached | grep -qE 'sk_[a-zA-Z0-9]{20,}'; then
  echo "ERROR: ElevenLabs API key detected in staged changes!"
  echo "Remove the key and use environment variables instead."
  exit 1
fi

Step 2: Environment-Specific Keys

Load the key at startup, fail fast when it is missing, and warn if a production

key leaks into development. Full getSecurityConfig() implementation:

references/implementation.md.

Step 3: Webhook HMAC Signature Verification

ElevenLabs webhooks carry an ElevenLabs-Signature header formatted as

t=TIMESTAMP,v1=SIGNATURE. Verify it with HMAC-SHA256, reject timestamps older

than 5 minutes (replay protection), and use a timing-safe comparison. Full

verifyWebhookSignature() implementation:

references/implementation.md.

Step 4: Express Webhook Endpoint with Verification

Verify against the raw request body, respond 200 fast, then process

asynchronously so you never trip the webhook timeout. Full endpoint:

references/implementation.md.

Step 5: API Key Rotation Procedure

Generate the new key, validate it before cutover, push to every environment,

verify production, then revoke the old key — zero downtime. Full runbook:

references/implementation.md.

Step 6: Voice Data Protection

Cloned voices are biometric PII: restrict who can clone, audit-log every

operation, and require documented consent. Full policy and audit logger:

ElevenLabs Upgrade & Migration

Overview

Guide for upgrading the ElevenLabs SDK and migrating between model generations.

Covers the JS SDK package rename (community elevenlabs → official

@elevenlabs/elevenlabs-js), model ID changes across generations, voice-settings

evolution, and API endpoint stability.

Work the seven steps below at a high level from this file; drill into

references/migration-guide.md for the full command

set and per-step code, and references/examples.md for three

end-to-end worked scenarios.

Authentication

All API calls authenticate with an account API key passed as the xi-api-key

header. Store it in the ELEVENLABSAPIKEY environment variable — never inline a

key in source. The SDK clients read the same value (process.env.ELEVENLABSAPIKEY

in Node, api_key=... in Python).

Prerequisites

• Current ElevenLabs SDK installed (Node or Python)
• ELEVENLABSAPIKEY exported in the environment
• Git for version control
• Test suite available
• Staging environment for validation

Instructions

The migration is a seven-step, branch-isolated workflow. Read package manifests and

config with Read, apply import/model changes with Edit, add new config files

(e.g. config/models.ts) with Write, and run the npm/pip/git commands via

Bash. Full commands and code for each step are in

references/migration-guide.md.

1. Check current versions — inspect installed Node/Python SDK versions and list

the models your account can reach.

1. JS SDK package migration — uninstall the legacy community elevenlabs

package, install @elevenlabs/elevenlabs-js, and update imports on an

upgrade/elevenlabs-sdk branch.

1. Model migration — map deprecated model IDs to current generations using the

migration table, and add a selectModel() helper that falls back off

eleven_v3 when WebSocket streaming is required.

1. Voice settings migration — verify stability, similarity_boost, style,

and speed against each model's capabilities.

1. API endpoint changes — confirm the stable /v1/ endpoints and adopt the

enhanced /v2/voices search where useful.

1. Python SDK upgrade — upgrade, pin the

ElevenLabs Webhooks & Events

Overview

ElevenLabs webhooks send HTTP POST notifications when async operations complete: transcription completion, post-call data from Conversational AI agents, and call initiation failures. Every delivery is signed with an HMAC-SHA256 signature you must verify before processing. This skill builds a secure endpoint that verifies signatures, routes events by type, and acks fast to avoid auto-disable.

Prerequisites

• ElevenLabs account (webhooks configured in Settings > Webhooks)
• HTTPS endpoint accessible from the internet
• Webhook secret (generated during webhook creation in dashboard)

Instructions

The full, copy-ready code for each step lives in references/implementation.md; per-event handlers live in references/examples.md. The high-level workflow:

1. Know the event types — subscribe only to what you handle (table below).
2. Create the webhook in the dashboard (Settings > Webhooks) and copy the HMAC secret.
3. Verify the signature with HMAC-SHA256 over ".", using a timing-safe compare and a 5-minute replay window. See the full verifier.
4. Handle the request with a raw body parser, ack 200 immediately, then process asynchronously. See the Express handler.
5. Route events to per-type handlers. See handler examples.
6. Guard against duplicates with idempotency keyed on the event ID. See idempotency.
7. Test locally by tunneling with ngrok. See local testing.

Webhook event types

Signature verification skeleton

// src/elevenlabs/webhook-verify.ts — Header: t=<unix_ts>,v1=<hex_sig>
export function verifyWebhookSignature(rawBody, signatureHeader, secret)