Integration in bestehende Systeme

ElevenLabs in Ihre bestehende Infrastruktur einzubinden, erfordert mehr als nur API-Aufrufe. Von SDKs über WebSocket-Streaming bis hin zu Caching-Strategien — hier lernen Sie die Best Practices für produktionsreife Integrationen.

Node.js SDK

Installation und Setup

npm install elevenlabs

import { ElevenLabsClient } from 'elevenlabs'

const client = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
})

// Text-to-Speech
const audioStream = await client.textToSpeech.convert('voice-id', {
  text: 'Hallo aus dem Node.js SDK!',
  model_id: 'eleven_multilingual_v2',
})

// Voices auflisten
const voices = await client.voices.getAll()

Python SDK

pip install elevenlabs

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="sk_...")

# Text-to-Speech
audio = client.text_to_speech.convert(
    voice_id="21m00Tcm4TlvDq8ikWAM",
    text="Hallo aus dem Python SDK!",
    model_id="eleven_multilingual_v2"
)

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

WebSocket Streaming

Bidirektionales Streaming

Für Echtzeit-Anwendungen verbinden Sie sich per WebSocket für Input-Streaming (Text chunk für chunk senden) und Output-Streaming (Audio chunk für chunk empfangen):

const ws = new WebSocket(
  `wss://api.elevenlabs.io/v1/text-to-speech/${voiceId}/stream-input?model_id=eleven_turbo_v2_5`
)

ws.onopen = () => {
  // Initialisierung
  ws.send(JSON.stringify({
    text: ' ',
    xi_api_key: process.env.ELEVENLABS_API_KEY,
    voice_settings: { stability: 0.5, similarity_boost: 0.75 },
  }))

  // Text in Chunks senden
  ws.send(JSON.stringify({ text: 'Dies ist der erste Satz. ' }))
  ws.send(JSON.stringify({ text: 'Und hier kommt der zweite. ' }))

  // Stream beenden
  ws.send(JSON.stringify({ text: '' }))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  if (data.audio) {
    // Base64-encoded Audio-Chunk verarbeiten
    const audioChunk = Buffer.from(data.audio, 'base64')
    // An Audio-Player oder Datei weiterleiten
  }
}

Vorteile von Input-Streaming

• LLM + TTS Pipeline: LLM generiert Token für Token, jeder Satz wird sofort an TTS gesendet
• Latenz: Erste Audio-Bytes während das LLM noch generiert
• Natürlichkeit: Pausen zwischen Sätzen wirken natürlicher

Webhook Callbacks

Asynchrone Verarbeitung

Für lange Texte (Bücher, Artikel) nutzen Sie Webhooks statt Polling:

// Job starten
const job = await client.textToSpeech.convertAsStream('voice-id', {
  text: longArticleText,
  model_id: 'eleven_multilingual_v2',
  webhook_url: 'https://your-server.com/api/elevenlabs-webhook',
})

// Webhook empfangen
app.post('/api/elevenlabs-webhook', (req, res) => {
  const { status, audio_url, duration } = req.body
  if (status === 'completed') {
    // Audio herunterladen und verarbeiten
    downloadAndStore(audio_url)
  }
  res.status(200).send('OK')
})

CDN Audio Delivery

Caching-Strategie für generierte Audios

Anfrage → Cache-Check → [Hit] → CDN liefert Audio
                      → [Miss] → ElevenLabs API → Audio generieren
                                → CDN speichern → Audio ausliefern

Implementation mit Cloudflare R2

async function getOrCreateAudio(text: string, voiceId: string) {
  const cacheKey = createHash('sha256')
    .update(`${voiceId}:${text}`)
    .digest('hex')

  // 1. Cache prüfen
  const cached = await r2.get(`audio/${cacheKey}.mp3`)
  if (cached) return cached.url

  // 2. Neu generieren
  const audio = await elevenLabsClient.textToSpeech.convert(voiceId, {
    text,
    model_id: 'eleven_multilingual_v2',
  })

  // 3. Im CDN speichern
  await r2.put(`audio/${cacheKey}.mp3`, audio, {
    httpMetadata: { contentType: 'audio/mpeg' },
  })

  return `https://cdn.example.com/audio/${cacheKey}.mp3`
}

Wann Caching sinnvoll ist

• Statische Inhalte: Begrüßungen, Menü-Ansagen, FAQ-Antworten
• E-Commerce: Produktbeschreibungen (ändern sich selten)
• E-Learning: Kurs-Audio einmal generieren, oft abspielen
• IVR-Systeme: Standard-Ansagen cachen, dynamische Teile live generieren

Kostenersparnis durch Caching

Praxis-Tipp: Implementieren Sie von Anfang an eine Caching-Schicht. Ohne Caching explodieren Ihre ElevenLabs-Kosten bei Skalierung. Die Faustregel: Jedes Audio, das zweimal abgespielt wird, sollte gecacht werden.