ElevenLabs Core Workflow B — Speech-to-Speech, Sound Effects & Audio Isolation

Overview

Secondary ElevenLabs workflows beyond TTS: (1) Speech-to-Speech voice conversion, (2) Sound Effects generation from text descriptions, (3) Audio Isolation for noise removal, and (4) Speech-to-Text transcription.

Prerequisites

• Completed elevenlabs-install-auth setup
• For STS: source audio file in MP3/WAV/M4A format
• For audio isolation: noisy audio file to clean

Instructions

Step 1: Speech-to-Speech (Voice Changer)

Transform audio from one voice to another using POST /v1/speech-to-speech/{voice_id}:

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream, createWriteStream } from "fs";
import { Readable } from "stream";
import { pipeline } from "stream/promises";

const client = new ElevenLabsClient();

async function speechToSpeech(
  sourceAudioPath: string,
  targetVoiceId: string,
  outputPath: string
) {
  const audio = await client.speechToSpeech.convert(targetVoiceId, {
    audio: createReadStream(sourceAudioPath),
    model_id: "eleven_english_sts_v2",  // STS-specific model
    voice_settings: JSON.stringify({
      stability: 0.5,
      similarity_boost: 0.8,
      style: 0.0,
    }),
    remove_background_noise: true,  // Built-in noise removal
  });

  await pipeline(Readable.fromWeb(audio as any), createWriteStream(outputPath));
  console.log(`Voice-converted audio saved to ${outputPath}`);
}

// Convert your voice recording to sound like "Rachel"
await speechToSpeech(
  "my_recording.mp3",
  "21m00Tcm4TlvDq8ikWAM",
  "converted.mp3"
);

cURL equivalent:

curl -X POST "https://api.elevenlabs.io/v1/speech-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
  -F "audio=@my_recording.mp3" \
  -F "model_id=eleven_english_sts_v2" \
  -F 'voice_settings={"stability":0.5,"similarity_boost":0.8}' \
  -F "remove_background_noise=true" \
  --output converted.mp3

Step 2: Sound Effects Generation

Generate cinematic sound effects from text descriptions using POST /v1/sound-generation:

async function generateSoundEffect(
  description: string,
  outputPath: string,
  options?: {
    duration?: number;      // 0.5-30 seconds (null = auto)
    promptInfluence?: number; // 0-1 (default 0.3, higher = follows prompt more closely)
    loop?: boolean;          // Seamless looping (default false)
  }
) {
  const audio = await client.textToSoundEffects.convert({
    text: description,
    duration_seconds: options?.duration,
    prompt_influence: options?.p

ElevenLabs Cost Tuning

Overview

Optimize ElevenLabs costs through model selection (Flash = 50% savings), character-efficient text processing, audio caching, and real-time quota monitoring. ElevenLabs bills by character for TTS and by audio minute for STT.

Prerequisites

• ElevenLabs account with usage dashboard access
• Understanding of your monthly character consumption
• Access to billing at https://elevenlabs.io/app/subscription

Instructions

Step 1: Understand the Billing Model

TTS billing (by character):

Other feature billing:

Plan character limits:

Step 2: Model-Based Cost Reduction

The easiest win: use Flash/Turbo models where quality difference is acceptable.

// src/elevenlabs/cost-aware-tts.ts
type ContentType = "greeting" | "notification" | "narration" | "premium";

function selectCostEffectiveModel(contentType: ContentType): {
  modelId: string;
  costMultiplier: number;
} {
  switch (contentType) {
    case "greeting":
    case "notification":
      // Short, functional audio — Flash is fine
      return { modelId: "eleven_flash_v2_5", costMultiplier: 0.5 };

    case "narration":
      // Content creation — quality matters
      return { modelId: "eleven_multilingual_v2", costMultiplier:

ElevenLabs Debug Bundle

Overview

Collect all diagnostic information needed for ElevenLabs support tickets. Gathers SDK version, API connectivity, quota status, voice inventory, and model availability while redacting all secrets.

Prerequisites

• ElevenLabs SDK installed
• API key configured (to test connectivity)
• Access to application logs

Instructions

Step 1: Create Debug Bundle Script

#!/bin/bash
# elevenlabs-debug-bundle.sh
set -euo pipefail

BUNDLE_DIR="elevenlabs-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

echo "=== ElevenLabs Debug Bundle ===" > "$BUNDLE_DIR/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- Environment ---
echo "--- Runtime Environment ---" >> "$BUNDLE_DIR/summary.txt"
node --version 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "Node.js: not found" >> "$BUNDLE_DIR/summary.txt"
python3 --version 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "Python: not found" >> "$BUNDLE_DIR/summary.txt"
echo "OS: $(uname -s) $(uname -r)" >> "$BUNDLE_DIR/summary.txt"
echo "API Key: ${ELEVENLABS_API_KEY:+SET (${#ELEVENLABS_API_KEY} chars)}" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- SDK Versions ---
echo "--- SDK Versions ---" >> "$BUNDLE_DIR/summary.txt"
npm list @elevenlabs/elevenlabs-js 2>/dev/null >> "$BUNDLE_DIR/summary.txt" || echo "JS SDK: not installed" >> "$BUNDLE_DIR/summary.txt"
pip show elevenlabs 2>/dev/null | grep -E "^(Name|Version)" >> "$BUNDLE_DIR/summary.txt" || echo "Python SDK: not installed" >> "$BUNDLE_DIR/summary.txt"
echo "" >> "$BUNDLE_DIR/summary.txt"

# --- API Connectivity ---
echo "--- API Connectivity ---" >> "$BUNDLE_DIR/summary.txt"
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
  https://api.elevenlabs.io/v1/user \
  -H "xi-api-key: ${ELEVENLABS_API_KEY:-missing}" 2>/dev/null || echo "FAILED")
echo "GET /v1/user: HTTP $HTTP_CODE" >> "$BUNDLE_DIR/summary.txt"

DNS_CHECK=$(dig +short api.elevenlabs.io 2>/dev/null | head -1 || echo "DNS lookup failed")
echo "DNS api.elevenlabs.io: $DNS_CHECK" >> "$BUNDLE_DIR/summary.txt"

TLS_CHECK=$(echo | openssl s_client -connect api.elevenlabs.io:443 2>/dev/null | grep -c "Verify return code: 0" || echo "0")
echo "TLS valid: $([ "$TLS_CHECK&

ElevenLabs Deploy Integration

Overview

Deploy ElevenLabs TTS/voice applications to cloud platforms. Covers Vercel (serverless), Fly.io (containers), and Google Cloud Run with proper secrets management, timeout configuration, and streaming support.

Prerequisites

• ElevenLabs API key for production
• Platform CLI installed (vercel, fly, or gcloud)
• Application code tested locally

Instructions

Vercel Deployment (Serverless)

Key constraint: Vercel functions have a 10-second timeout on Hobby (30s on Pro). Use Flash model for speed.

# Set secrets
vercel env add ELEVENLABS_API_KEY production
vercel env add ELEVENLABS_API_KEY preview

# Deploy
vercel --prod

API Route (Next.js / Vercel):

// app/api/tts/route.ts
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { NextResponse } from "next/server";

export const runtime = "nodejs";
export const maxDuration = 30; // Vercel Pro max

const client = new ElevenLabsClient();

export async function POST(req: Request) {
  const { text, voiceId = "21m00Tcm4TlvDq8ikWAM" } = await req.json();

  if (!text || text.length > 5000) {
    return NextResponse.json(
      { error: "Text required, max 5000 characters" },
      { status: 400 }
    );
  }

  try {
    const audio = await client.textToSpeech.convert(voiceId, {
      text,
      model_id: "eleven_flash_v2_5",  // Fast for serverless
      output_format: "mp3_22050_32",
      voice_settings: {
        stability: 0.5,
        similarity_boost: 0.75,
      },
    });

    return new Response(audio as any, {
      headers: {
        "Content-Type": "audio/mpeg",
        "Cache-Control": "public, max-age=3600",
      },
    });
  } catch (error: any) {
    const status = error.statusCode || 500;
    return NextResponse.json(
      { error: error.message || "TTS generation failed" },
      { status }
    );
  }
}

vercel.json:

{
  "env": {
    "ELEVENLABS_API_KEY": "@elevenlabs_api_key"
  },
  "functions": {
    "app/api/tts/route.ts": {
      "maxDuration": 30
    }
  }
}

Fly.io Deployment (Container)

Better for long-running TTS, WebSocket streaming, and high concurrency.

fly.toml:

app = "my-tts-service"
primary_region = "iad"

[env]
  NODE_ENV = "production"
  # Use the closest region to ElevenLabs servers (US East)
  ELEVENLABS_MODEL = "eleven_multilingual_v2"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machin

ElevenLabs Hello World

Overview

Generate speech from text using the ElevenLabs TTS API. This skill covers the core POST /v1/text-to-speech/{voice_id} endpoint with real voice IDs, model selection, and audio output.

Prerequisites

• Completed elevenlabs-install-auth setup
• Valid API key in ELEVENLABSAPIKEY

Instructions

Step 1: Text-to-Speech with the SDK

TypeScript (recommended):

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";
import { Readable } from "stream";
import { pipeline } from "stream/promises";

const client = new ElevenLabsClient();

async function generateSpeech() {
  // Use a pre-made voice — "Rachel" is a default voice available on all accounts
  // Find voice IDs via: GET /v1/voices
  const audio = await client.textToSpeech.convert("21m00Tcm4TlvDq8ikWAM", {
    text: "Hello! This is your first ElevenLabs text-to-speech generation.",
    model_id: "eleven_multilingual_v2",  // Best quality, 29 languages
    voice_settings: {
      stability: 0.5,           // 0-1: lower = more expressive
      similarity_boost: 0.75,   // 0-1: higher = closer to original voice
      style: 0.0,               // 0-1: higher = more dramatic (costs more latency)
      speed: 1.0,               // 0.7-1.2: speech speed multiplier
    },
  });

  // audio is a ReadableStream — pipe to file
  await pipeline(
    Readable.fromWeb(audio as any),
    createWriteStream("output.mp3")
  );

  console.log("Audio saved to output.mp3");
}

generateSpeech().catch(console.error);

Python:

from elevenlabs.client import ElevenLabsClient

client = ElevenLabsClient()

audio = client.text_to_speech.convert(
    voice_id="21m00Tcm4TlvDq8ikWAM",  # Rachel
    text="Hello! This is your first ElevenLabs text-to-speech generation.",
    model_id="eleven_multilingual_v2",
    voice_settings={
        "stability": 0.5,
        "similarity_boost": 0.75,
        "style": 0.0,
    },
)

with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

print("Audio saved to output.mp3")

Step 2: Using cURL (Raw REST API)

curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/21m00Tcm4TlvDq8ikWAM" \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from the ElevenLabs API!",
    "model_id": "eleven_multilingual_v2",
    "voice_settings": {
      "stability": 0.5,
      "

ElevenLabs Install & Auth

Overview

Set up the ElevenLabs SDK and configure API key authentication. ElevenLabs uses a single API key (xi-api-key header) for all endpoints at api.elevenlabs.io.

Prerequisites

• Node.js 18+ or Python 3.10+
• ElevenLabs account (free tier works) at https://elevenlabs.io
• API key from Profile > API Keys in the ElevenLabs dashboard

Instructions

Step 1: Install the SDK

Node.js (official package: @elevenlabs/elevenlabs-js):

npm install @elevenlabs/elevenlabs-js
# or
pnpm add @elevenlabs/elevenlabs-js

Python (official package: elevenlabs):

pip install elevenlabs

Step 2: Configure API Key

# Set environment variable (all SDKs auto-detect this)
export ELEVENLABS_API_KEY="sk_your_key_here"

# Or create .env file
echo 'ELEVENLABS_API_KEY=sk_your_key_here' >> .env

Add to .gitignore:

.env
.env.local
.env.*.local

Step 3: Initialize the Client

TypeScript:

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
  // Optional: configure retries (default: 2)
  maxRetries: 3,
  // Optional: configure timeout in seconds
  timeoutInSeconds: 30,
});

Python:

import os
from elevenlabs.client import ElevenLabsClient

client = ElevenLabsClient(
    api_key=os.environ.get("ELEVENLABS_API_KEY")
)

Step 4: Verify Connection

TypeScript:

async function verifyConnection() {
  // List available voices to confirm auth works
  const voices = await client.voices.getAll();
  console.log(`Connected. ${voices.voices.length} voices available.`);

  // Check subscription/quota
  const user = await client.user.get();
  console.log(`Plan: ${user.subscription.tier}`);
  console.log(`Characters used: ${user.subscription.character_count}/${user.subscription.character_limit}`);
}

verifyConnection().catch(console.error);

Python:

def verify_connection():
    voices = client.voices.get_all()
    print(f"Connected. {len(voices.voices)} voices available.")

    user = client.user.get()
    print(f"Plan: {user.subscription.tier}")
    print(f"Characters used: {user.subscription.character_count}/{user.subscription.character_limit}")

verify_connection()

cURL (raw API):

curl -s htt

ElevenLabs Local Dev Loop

Overview

Set up a fast, cost-effective local development workflow for ElevenLabs audio projects. Includes SDK mocking to avoid burning character quota during development, audio output testing, and hot-reload patterns.

Prerequisites

• Completed elevenlabs-install-auth setup
• Node.js 18+ with npm/pnpm
• vitest for testing (recommended)

Instructions

Step 1: Project Structure

my-elevenlabs-project/
├── src/
│   ├── elevenlabs/
│   │   ├── client.ts       # Singleton client wrapper
│   │   ├── config.ts       # Environment-aware config
│   │   └── tts.ts          # TTS service layer
│   └── index.ts
├── tests/
│   ├── __mocks__/
│   │   └── elevenlabs.ts   # SDK mock for free testing
│   ├── tts.test.ts
│   └── fixtures/
│       └── sample.mp3      # Known-good audio for comparison
├── output/                  # Generated audio (git-ignored)
├── .env.local               # Local API key (git-ignored)
├── .env.example             # Template for team
└── package.json

Step 2: Environment Configuration

// src/elevenlabs/config.ts
export interface ElevenLabsConfig {
  apiKey: string;
  modelId: string;
  defaultVoiceId: string;
  outputFormat: string;
}

export function loadConfig(): ElevenLabsConfig {
  const env = process.env.NODE_ENV || "development";

  return {
    apiKey: process.env.ELEVENLABS_API_KEY || "",
    // Use cheaper/faster model in dev, high-quality in prod
    modelId: env === "production"
      ? "eleven_multilingual_v2"    // 1.0 credits/char, best quality
      : "eleven_flash_v2_5",       // 0.5 credits/char, ~75ms latency
    defaultVoiceId: process.env.ELEVENLABS_VOICE_ID || "21m00Tcm4TlvDq8ikWAM",
    outputFormat: "mp3_22050_32",  // Smaller files for dev
  };
}

Step 3: Mock the SDK for Unit Tests

// tests/__mocks__/elevenlabs.ts
// Avoids API calls (and character charges) during testing
import { vi } from "vitest";
import { readFileSync } from "fs";

const sampleAudio = readFileSync("tests/fixtures/sample.mp3");

export const mockElevenLabsClient = {
  textToSpeech: {
    convert: vi.fn().mockResolvedValue(
      new ReadableStream({
        start(controller) {
          controller.enqueue(sampleAudio);
          controller.close();
        },
      })
    ),
    stream: vi.fn().mockImplementation(async function* () {
      yield sampleAudio.subarray(0, 1024);
      yield sampleAudio.subarray(1024);
    }),
  },
  voices: {
    getAll: vi.fn().mockResolvedValue({
      voices: [
        { voice_id: "21m00Tcm4TlvDq8ikWAM", name: "Rachel" },
        { voice_id: "ErXwobaYiN019PkySvjV", name: "Antoni" },
      ],
    }),
  },
  user: {

ElevenLabs Performance Tuning

Overview

Optimize ElevenLabs TTS latency and throughput through model selection, streaming strategies, audio format tuning, and caching. Latency ranges from ~75ms (Flash) to ~500ms (v3) depending on configuration.

Prerequisites

• ElevenLabs SDK installed
• Understanding of your latency requirements
• Audio playback infrastructure (browser, mobile, server-side)

Instructions

Step 1: Model Selection for Latency

The single biggest performance lever is model choice:

// Select model based on use case
function selectModel(useCase: "realtime" | "balanced" | "quality" | "max_quality"): string {
  const models = {
    realtime:    "eleven_flash_v2_5",
    balanced:    "eleven_turbo_v2_5",
    quality:     "eleven_multilingual_v2",
    max_quality: "eleven_v3",
  };
  return models[useCase];
}

Step 2: Output Format Optimization

Smaller formats = faster transfer:

// Use smaller format for streaming, higher quality for downloads
const streamingConfig = {
  output_format: "mp3_22050_32",  // 4 KB/s — fast streaming
  model_id: "eleven_flash_v2_5",   // ~75ms first byte
};

const downloadConfig = {
  output_format: "mp3_44100_128", // 16 KB/s — high quality
  model_id: "eleven_multilingual_v2",
};

Step 3: HTTP Streaming for Time-to-First-Byte

Use the streaming endpoint to start pla

ElevenLabs Rate Limits

Overview

Handle ElevenLabs rate limits with plan-aware concurrency queuing, exponential backoff, and quota monitoring. ElevenLabs uses two rate limit mechanisms: concurrent request limits (per plan) and system-level throttling.

Prerequisites

• ElevenLabs SDK installed
• Understanding of your subscription plan's limits
• p-queue package (recommended): npm install p-queue

Instructions

Step 1: Understand the Two 429 Error Types

ElevenLabs returns HTTP 429 for two different reasons:

Step 2: Plan Concurrency Limits

Step 3: Concurrency-Aware Request Queue

// src/elevenlabs/rate-limiter.ts
import PQueue from "p-queue";

type ElevenLabsPlan = "free" | "starter" | "creator" | "pro" | "scale" | "business";

const CONCURRENCY_LIMITS: Record<ElevenLabsPlan, number> = {
  free: 2,
  starter: 3,
  creator: 5,
  pro: 10,
  scale: 15,
  business: 15,
};

export function createRequestQueue(plan: ElevenLabsPlan) {
  const concurrency = CONCURRENCY_LIMITS[plan];

  const queue = new PQueue({
    concurrency,
    // Each queued request adds ~50ms to response time
    // so keep queue depth reasonable
    timeout: 120_000,  // 2 minute timeout per request
    throwOnTimeout: true,
  });

  queue.on("error", (error) => {
    console.error("[ElevenLabs Queue] Request failed:", error.message);
  });

  return queue;
}

// Usage
const queue = createRequestQueue("pro"); // 10 concurrent

async function generateWithQueue(voiceId: string, text: string) {
  return queue.add(async () => {
    return client.textToSpeech.convert(voiceId, {
      text,
      model_id: "eleven_flash_v2_5",
    });
  });
}

// All 20 requests run with max 10 concurrent
const results = await Promise.all(
  texts.map(text => gener

ElevenLabs Reference Architecture

Overview

Production-ready architecture for ElevenLabs TTS/voice applications. Covers project layout, service layers, caching, streaming, and multi-model orchestration.

Prerequisites

• Understanding of layered architecture patterns
• ElevenLabs SDK knowledge (see elevenlabs-sdk-patterns)
• TypeScript project with async patterns
• Redis (optional, for distributed caching)

Instructions

Step 1: Project Structure

my-elevenlabs-service/
├── src/
│   ├── elevenlabs/
│   │   ├── client.ts            # Singleton client with retry config
│   │   ├── config.ts            # Environment-aware configuration
│   │   ├── models.ts            # Model selection logic
│   │   ├── errors.ts            # Error classification (see sdk-patterns)
│   │   └── types.ts             # TypeScript interfaces
│   ├── services/
│   │   ├── tts-service.ts       # Text-to-Speech orchestration
│   │   ├── voice-service.ts     # Voice management (clone, list, settings)
│   │   ├── audio-service.ts     # SFX, isolation, transcription
│   │   └── cache-service.ts     # Audio caching layer
│   ├── api/
│   │   ├── routes/
│   │   │   ├── tts.ts           # POST /api/tts
│   │   │   ├── voices.ts        # GET/POST /api/voices
│   │   │   ├── webhooks.ts      # POST /webhooks/elevenlabs
│   │   │   └── health.ts        # GET /health
│   │   └── middleware/
│   │       ├── rate-limit.ts    # Request throttling
│   │       └── auth.ts          # Your app's auth (not ElevenLabs auth)
│   ├── queue/
│   │   ├── tts-queue.ts         # Async TTS job processing
│   │   └── workers.ts           # Queue workers
│   └── monitoring/
│       ├── metrics.ts           # Latency, error rate, quota tracking
│       └── alerts.ts            # Budget and health alerts
├── tests/
│   ├── unit/
│   │   ├── tts-service.test.ts
│   │   └── cache-service.test.ts
│   └── integration/
│       └── tts-smoke.test.ts
├── config/
│   ├── development.json
│   ├── staging.json
│   └── production.json
└── .env.example

Step 2: Configuration Layer

// src/elevenlabs/config.ts
export interface ElevenLabsConfig {
  apiKey: string;
  environment: "development" | "staging" | "production";
  defaults: {
    modelId: string;
    voiceId: string;
    outputFormat: string;
    voiceSettings: {
      stability: number;
      similarity_boost: number;
      style: number;
      speed: number;
    };
  };
  performance: {
    maxConcurrency: number;
    timeoutMs: number;
    maxRetries: number;
  };
  cache: {
    enabled: boolean;
    maxSizeMB: number;
    ttlSeconds: number;
  };
}

const ENV_CONFIGS: Record<string, Partial<ElevenLabsConfig>> = {
  development: {
    defaults: {
      modelId: "eleven_flash_v2_5",    // Cheap + fast for dev
      voiceId: "21m00Tc

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

// src/elevenlabs/client.ts
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,        // Auto-retry on 429/5xx (default: 2)
      timeoutInSeconds: 60, // Per-request timeout
    });
  }
  return instance;
}

// Reset for testing
export function resetClient(): void {
  instance = null;
}

Pattern 2: Type-Safe TTS Service

// src/elevenlabs/tts-service.ts
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

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.

Prerequisites

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

Instructions

Step 1: API Key Management

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

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

Git pre-commit hook to prevent accidental key commits:

#!/bin/bash
# .git/hooks/pre-commit
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

// src/elevenlabs/config.ts
interface ElevenLabsSecurityConfig {
  apiKey: string;
  webhookSecret: string;
  environment: "development" | "staging" | "production";
}

export function getSecurityConfig(): ElevenLabsSecurityConfig {
  const env = (process.env.NODE_ENV || "development") as ElevenLabsSecurityConfig["environment"];

  const apiKey = process.env.ELEVENLABS_API_KEY;
  if (!apiKey) {
    throw new Error("ELEVENLABS_API_KEY is required");
  }

  // Warn if production key is used in dev
  if (env === "development" && apiKey.startsWith("sk_live_")) {
    console.warn("WARNING: Using production API key in development environment");
  }

  return {
    apiKey,
    webhookSecret: process.env.ELEVENLABS_WEBHOOK_SECRET || "",
    environment: env,
  };
}

Step 3: Webhook HMAC Signature Verification

ElevenLabs webhooks include an ElevenLabs-Signature header for HMAC verification:

// src/elevenlabs/webhook-verify.ts
import crypto from "crypto";

/**
 * Verify ElevenLabs webhook signature using HMAC-SHA256.
 * The shared secret is generated when you create a webhook in the dashboard.
 */
export function verifyWebhookSignature(
  payload: string | Buffer,
  signatureHeader: string,
  secret: string
): boolean {
  if (!signatureHeader || !secret) return false;

  // ElevenLabs signature format: t=<timestamp>,v1=<signature>
  const parts = signatureHeader.split(",");
  const timestamp = parts.find(p => p.startsWith("t="))?.slice(2);
  const signature = parts.find(p => p.startsWith("v1="))?.slice(3);

  if (!timestamp || !signature) return false;

  // Reject timestamps older than 5

ElevenLabs Upgrade & Migration

Overview

Guide for upgrading the ElevenLabs SDK and migrating between model generations. Covers the JS SDK package rename, model ID changes, and API endpoint evolution.

Prerequisites

• Current ElevenLabs SDK installed
• Git for version control
• Test suite available
• Staging environment for validation

Instructions

Step 1: Check Current Versions

# Node.js SDK
npm list @elevenlabs/elevenlabs-js 2>/dev/null || npm list elevenlabs 2>/dev/null
npm view @elevenlabs/elevenlabs-js version

# Python SDK
pip show elevenlabs | grep -E "^(Name|Version)"

# Check what models your account has access to
curl -s https://api.elevenlabs.io/v1/models \
  -H "xi-api-key: ${ELEVENLABS_API_KEY}" | \
  jq '[.[] | {model_id, name}]'

Step 2: JS SDK Package Migration

The official Node.js package changed names:

Migration steps:

# Remove old package
npm uninstall elevenlabs

# Install current official SDK
npm install @elevenlabs/elevenlabs-js

# Create upgrade branch
git checkout -b upgrade/elevenlabs-sdk

Update imports:

// BEFORE (legacy community package)
import ElevenLabs from "elevenlabs";
const client = new ElevenLabs({ apiKey: "..." });

// AFTER (official SDK)
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
  maxRetries: 3,
  timeoutInSeconds: 60,
});

Step 3: Model Migration Guide

ElevenLabs models evolve across generations. Migration paths:

# Create webhook in ElevenLabs dashboard:
# Settings > Webhooks > Create Webhook
# - URL: https://your-app.com/webhooks/elevenlabs
# - Select event types to subscribe to
# - Copy the generated HMAC secret

// src/elevenlabs/webhook-verify.ts
import crypto from "crypto";

/**
 * Verify the ElevenLabs-Signature header using HMAC-SHA256.
 *
 * Header format: t=<unix_timestamp>,v1=<hex_signature>
 * Signed payload: "<timestamp>.<raw_body>"
 */
export function verifyWebhookSignature(
  rawBody: string | Buffer,
  signatureHeader: string,
  secret: string
): { valid: boolean; reason?: string } {
  if (!signatureHeader || !secret) {
    return { valid: false, reason: "Missing signature header or secret" };
  }

  // Parse header: t=1234567890,v1=abcdef...
  const parts = new Map(
    signatureHeader.split(",").map(p => {
      const [key, ...val] = p.split("=");
      return [key, val.join("=")] as [string, string];
    })
  );

  const timestamp = parts.get("t");
  const signature = parts.get("v1");

  if (!timestamp || !signature) {
    return { valid: false, reason: "Malformed signature header" };
  }

  // Replay protection: reject if older than 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) {
    return { valid: false, reason: `Timestamp too old: ${age}s` };
  }

  // Compute expected HMAC
  cons