Text to Speech API-Integration: Streaming, Batching, Retries

Die Integration einer Text to Speech API ist einfach – nachdem Sie einige grundlegende Entscheidungen getroffen haben: Welchen Übertragungsmodus nutzen Sie? Welches Modell und Ausgabeformat wählen Sie? Wie streamen Sie? Wie verarbeiten Sie große Mengen, ohne Ihr Parallelitätslimit zu überschreiten? Wie cachen und wiederholen Sie Anfragen, damit Sie nie zweimal für dasselbe Audio zahlen? Und wie vergleichen Sie die Time-to-First-Byte mit anderen Anbietern?

Um Ihnen bei der Integration der Text to Speech API zu helfen, haben wir jede dieser Architekturentscheidungen aufgeschlüsselt und erklärt, was zu tun ist. Dieser Leitfaden hilft Ihnen, die ElevenLabs Text to Speech API zu integrieren und zu skalieren – mit Codebeispielen, die Sie direkt in die Produktion übernehmen können.

Für einen umfassenden Hintergrund zu den hier genannten Konzepten lesen Sie unsere Leitfäden zu Audio-Streaming verstehen, Latenz optimieren und zur Modellübersicht von ElevenLabs.

Zusammenfassung

• Es gibt einen ElevenLabs Text to Speech API-Endpunkt, den Sie auf drei Arten nutzen können: Batch-Konvertierung, HTTP-Streaming und Stream-Input über WebSocket.
• Bei HTTP zählt jede laufende Anfrage gegen Ihr Parallelitätslimit, während bei WebSocket nur die aktive Generierung zählt.
• Setzen Sie Ihre Parallelität knapp unter Ihr Tariflimit und cachen Sie einen Hash aller ausgabe-relevanten Parameter, damit Sie nie zweimal für denselben Text zahlen.
• Wiederholen Sie 429- und 5xx-Fehler mit exponentiellem Backoff und vollem Jitter, um vor dem Erreichen des Parallelitätslimits nachzulassen.

Drei Wege zur Integration der Text to Speech API

Es gibt einen Text to Speech-Endpunkt, aber die Art der Integration beeinflusst Latenz, Komplexität und Kosten.

Der gleiche POST /v1/text-to-speech/{voice_id}-Aufruf funktioniert in drei Varianten, die jeweils für unterschiedliche Anwendungsfälle geeignet sind. Hier die Übersicht:

• Batch (Konvertierung) ist die einfachste Integration: Sie senden eine Anfrage und erhalten eine Audio-Antwort. Es ist die Option mit der geringsten Komplexität und der höchsten Time-to-First-Audio, da der gesamte Clip vor der Rückgabe erzeugt wird.
• HTTP-Streaming (stream) nutzt die gleiche Anfrage, aber teilt die Antwort in Blöcke: Sie hängen /stream an den Pfad an, rufen die Stream-Methode auf und erhalten das Audio als gestückelte Antwort. Der Code ist fast identisch, aber die wahrgenommene Latenz ist deutlich geringer.
• Der WebSocket (stream-input) hält eine dauerhafte Verbindung: Sie senden Text schrittweise und erhalten währenddessen Audio-Blöcke zurück. Dies ist für interaktive Agenten und für das direkte Umwandeln von LLM-Ausgaben in Sprache gedacht, noch bevor der Satz fertig ist.

Streaming beschleunigt die Audio-Generierung nicht; die Inferenzzeit bleibt gleich. Streaming verändert nur, wann Sie das erste Stück erhalten: Es wird gesendet, bevor der gesamte Clip fertig ist, sodass die Wartezeit für den Nutzer kürzer erscheint, obwohl der Gesamtaufwand gleich bleibt.

Entscheidungstabelle: Batch vs. Streaming vs. WebSocket

Bei der Wahl zwischen diesen drei Methoden sollten Sie mehrere Faktoren berücksichtigen.

Als schnelle Orientierung: Wählen Sie Batch für Offline-Rendering, HTTP-Streaming für bekannten Text, auf den ein Nutzer wartet, und WebSocket für Agenten und Live-LLM zu Sprache.

Die folgende Tabelle zeigt die wichtigsten Unterschiede für den Einsatz im großen Maßstab.

Bei HTTP – egal ob Batch oder Streaming – zählt jede laufende Anfrage für die gesamte Dauer gegen Ihr Parallelitätslimit. Bei WebSocket zählt nur die Zeit, in der das Modell tatsächlich Audio generiert; eine offene, aber inaktive Verbindung verursacht kaum Kosten.

Für einen kaskadierten Voice-Agenten, der eine Verbindung über ein ganzes Gespräch offen hält, aber nur während der Agenten-Turns Audio generiert, ist dieser Unterschied groß – das ist der Hauptgrund, WebSockets für Agenten zu nutzen. Das vollständige Protokoll finden Sie im Echtzeit-Text to Speech WebSocket-Leitfaden.

Modell- und Ausgabeformat wählen

Zwei Entscheidungen bestimmen das zurückgegebene Audio Ihrer TTS-API-Integration: Erstens das Modell, das Qualität und Geschwindigkeit festlegt. Zweitens das Ausgabeformat, das Container, Bitrate und Samplerate bestimmt.

Wenn Sie beides von Anfang an richtig wählen, stimmen auch alle nachgelagerten Faktoren wie Latenz und Telefonie-Kompatibilität.

Modelle

Wir bieten mehrere Text to Speech-Modelle an. Sie sind nicht von „am besten“ bis „am schlechtesten“ sortiert; jedes Modell hat eigene Stärken.

Die ~75ms beziehen sich auf die reine Modell-Inferenz unter typischen Bedingungen, ohne Netzwerk- und Anwendungs-Latenz. Die Zeit steigt bei längeren Eingaben und unter Last. Messen Sie immer in Ihrer eigenen Anwendung, nicht anhand von Benchmark-Zahlen.

Flash-Modelle sind kleiner und nutzen stärkere Approximationen, um die Inferenzzeit zu reduzieren. Eleven v3 und Multilingual v2 sind größere Modelle, die pro Zeichen mehr Rechenzeit für ein detailreicheres Ergebnis aufwenden. Es gibt keine Einstellung, die Eleven v3-Qualität mit Flash-Geschwindigkeit liefert, da die Qualität auf zusätzlicher Berechnung basiert.

Für Echtzeit- oder Agenten-Anwendungen nutzen Sie eleven_flash_v2_5 – das ist die schnellste mehrsprachige Option. Für Erzählungen, Hörbücher oder Marketing-Voiceover nutzen Sie eleven_multilingual_v2 für stabile, hohe Qualität oder eleven_v3 für maximale Ausdrucksstärke und emotionale Bandbreite.

Wenn Aussprache wichtig ist, etwa bei Telefonnummern, Daten oder Währungen, normalisieren Sie die Zahlen selbst in Ihrer Anwendung, bevor der Text an die API geht. Schreiben Sie die gewünschte gesprochene Form aus.

Eigene Normalisierung sorgt für vorhersehbare Aussprache über alle Modelle hinweg und vermeidet Abhängigkeiten von modell-spezifischen Standards, die sich ändern können.

Ausgabeformat

Der Parameter output_format steuert Container, Samplerate und Bitrate des zurückgegebenen Audios. Die wichtigsten Werte:

Stimmen-Einstellungen

Mit diesen Einstellungen steuern Sie, wie die generierte Sprache ausgegeben wird:

• Stabilität: Steuert Konsistenz versus Ausdrucksstärke. Niedrige Werte erzeugen variablere, ausdrucksstärkere Sprache, hohe Werte sorgen für gleichmäßigere, vorhersehbare Wiedergabe.
• SimilarityBoost: Steuert, wie nah das Ergebnis an der Referenzstimme bleibt.
• Stil: Verstärkt den natürlichen Sprechstil der Stimme bei höheren Werten.
• useSpeakerBoost: Verstärkt die Ähnlichkeit zum Originalsprecher bei minimaler Latenzsteigerung.
• Geschwindigkeit: Passt das Sprechtempo um den Standardwert 1.0 an.

Von diesen Einstellungen hat Stabilität meist den größten Einfluss auf die wahrgenommene Qualität. Niedrige Werte erzeugen ausdrucksstärkere, aber weniger konsistente Ergebnisse, hohe Werte setzen auf Konsistenz und Vorhersehbarkeit.

Für die niedrigste Latenz wählen Sie Flash in Kombination mit einem Instant Voice Clone oder einer Standardstimme; Professionelle Voice Clones klingen hervorragend, verursachen aber zusätzlichen Aufwand pro Generierung.

In diesem Leitfaden ist die Beispiel-voice_id JBFqnCBsd6RMkjVDRZzb (George).

Streaming-Integration (HTTP und WebSocket)

In diesem Abschnitt geht es um die praktische Umsetzung der Text to Speech API-Integration: SDK installieren, Stream öffnen und Audio empfangen. Der HTTP-Weg deckt die meisten Web- und App-Anwendungen ab, der WebSocket-Weg Agenten und Live-LLM-Ausgaben.

Beide Wege setzen voraus, dass Sie den ElevenLabs-Client wie unten initialisiert haben.

npm install @elevenlabs/elevenlabs-js

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

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

Beim Streaming wird ein Stream geöffnet und die Audio-Blöcke werden verarbeitet, sobald sie eintreffen. voiceId ist das erste Argument, gefolgt von einem Options-Objekt mit camelCase-Schlüsseln (modelId, outputFormat, voiceSettings):

const stream = await elevenlabs.textToSpeech.stream("JBFqnCBsd6RMkjVDRZzb", {
  text,
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
  voiceSettings: { stability: 0, similarityBoost: 1.0, style: 0, useSpeakerBoost: true, speed: 1.0 },
});

for await (const chunk of stream) {
  // chunk is a Buffer; feed it to the player as it arrives
}

Für die WebSocket-Variante verbinden Sie sich mit wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input, senden eine erste Nachricht mit Ihren Stimmeinstellungen und einem führenden Leerzeichen, dann senden Sie Textnachrichten, sobald sie verfügbar sind, und lesen JSON-Frames zurück, deren audio-Feld base64-codierte Blöcke enthält.

Batching und Parallelitätsgrenzen für hohe Auslastung

Die Integration mit hoher Auslastung wird durch Parallelität bestimmt – also die Anzahl der Anfragen, die gleichzeitig Audio generieren. Jeder Tarif hat ein Limit pro Modellfamilie.

Jeder Tarif hat ein eigenes Parallelitätslimit:

• Free: 4 gleichzeitige Flash-Anfragen.
• Starter: 6 gleichzeitige Flash-Anfragen.
• Creator: 10 gleichzeitige Flash-Anfragen.
• Pro: 20 gleichzeitige Flash-Anfragen.
• Scale und Business: 30 gleichzeitige Flash-Anfragen, Enterprise-Limits individuell.

Multilingual v2-Limits liegen etwa bei der Hälfte der oben genannten Werte.

Ein begrenzter Pool verhindert Überlastung, indem er die Anzahl gleichzeitiger Anfragen begrenzt:

// Set MAX_CONCURRENCY at or below your plan's Flash concurrency limit.
const MAX_CONCURRENCY = 8;

async function synthMany(texts: string[]): Promise<Buffer[]> {
  const results: Buffer[] = [];
  for (let i = 0; i < texts.length; i += MAX_CONCURRENCY) {
    const batch = texts.slice(i, i + MAX_CONCURRENCY);
    results.push(...(await Promise.all(batch.map(eachSingleRequest)))); // never more than MAX_CONCURRENCY in flight
  }
  return results;

Setzen Sie MAX_CONCURRENCY etwas unter Ihr Tariflimit, nicht exakt darauf. Dieser Puffer fängt weiteren Traffic mit demselben Schlüssel ab und hält Sie unter der Schwelle, bei der ein 429 zurückgegeben wird.

Zeichenlimits und Aufteilung langer Texte

Jedes Modell hat ein Zeichenlimit pro Anfrage. Jede Langtext-Integration muss Texte aufteilen und das Audio wieder zusammensetzen.

Hier die Zeichenlimits pro Anfrage für jedes Modell:

• Flash v2.5: Bis zu 40.000 Zeichen pro Anfrage.
• Flash v2: Bis zu 30.000 Zeichen pro Anfrage.
• Multilingual v2: Bis zu 10.000 Zeichen pro Anfrage.
• Eleven v3: Bis zu 5.000 Zeichen pro Anfrage.

Längere Texte müssen in mehrere Anfragen aufgeteilt werden. Teilen Sie möglichst an Satzgrenzen, damit die Prosodie an den Schnittstellen erhalten bleibt.

function splitText(text: string, maxChars: number): string[] {
  const sentences = text.trim().split(/(?<=[.!?])\s+/);
  const chunks: string[] = [];
  let current = "";
  for (let sentence of sentences) {
    if (current.length + sentence.length + 1 > maxChars) {
      if (current) chunks.push(current.trim());
      // A single sentence longer than the limit is hard-split.
      while (sentence.length > maxChars) {
        chunks.push(sentence.slice(0, maxChars));
        sentence = sentence.slice(maxChars);
      }
      current = sentence;
    } else {
      current = `${current} ${sentence}`.trim();
    }
  }
  if (current) chunks.push(current.trim());
  return chunks;
}

Rendern Sie die Blöcke in der richtigen Reihenfolge und fügen Sie das Audio zusammen. Bei Langtexten, bei denen jeder Block unabhängig ist, können Sie die beiden Schritte direkt kombinieren: Geben Sie die Ausgabe von splitText in den begrenzten Pool und lassen Sie ihn den Rest erledigen.

Caching und Idempotenz

Text to Speech-Ausgaben sind so deterministisch, dass das erneute Rendern desselben Textes mit denselben Einstellungen unnötig ist. Cachen Sie das Ergebnis anhand eines Hashs aller audio-relevanten Eingaben; derselbe Schlüssel dient auch als Idempotenz-Token bei Wiederholungen.

So setzen Sie beides um.

import { createHash } from "node:crypto";

function cacheKey(text: string, voiceId: string, modelId: string,
                  outputFormat: string, settings: object): string {
  // Every parameter that changes the audio must be in the key.
  const payload = JSON.stringify({ text, voiceId, modelId, outputFormat, settings });
  return createHash("sha256").update(payload).digest("hex");
}

async function cachedSynth(text: string, voiceId: string, modelId: string,
                           outputFormat: string, settings: object): Promise<Buffer> {
  const key = cacheKey(text, voiceId, modelId, outputFormat, settings);
  const cached = await cacheGet(key);          // e.g. read from disk or S3
  if (cached) return cached;

  const audio = await elevenlabs.textToSpeech.convert(voiceId, { text, modelId, outputFormat });
  await cachePut(key, audio);                   // store the bytes under the key
  return audio;
}

Die Regel: Jeder Parameter, der das Audio verändert, muss in den Schlüssel einfließen – inklusive outputFormat und Stimmeinstellungen. Richtig umgesetzt, dient der Schlüssel als Idempotenz-Token. Wenn ein Client eine bereits erfolgreiche Anfrage wiederholt, liefern Sie die gecachten Bytes zurück, statt neu zu generieren.

Fehlerbehandlung und Rate Limits (429er)

Ein Produktiv-Client benötigt Wiederholungen mit Backoff und Jitter sowie eine Behandlung, die je nach Statuscode variiert – denn nicht jeder Fehler sollte wiederholt werden.

Die folgende Tabelle ordnet jedem Status die richtige Aktion zu und erklärt, warum ein 429 ein weiches Limit ist.

Ein 429 ist kein hartes Limit. Wenn Sie das Parallelitätslimit überschreiten, werden Anfragen zunächst nach Priorität in eine Warteschlange gestellt, was meist etwa 50ms Verzögerung bedeutet. Erst wenn Sie weiterhin über dem Limit liegen, erhalten Sie einen 429.

Die Antwort enthält außerdem Header für current-concurrent-requests und maximum-concurrent-requests, die Ihren aktuellen Puffer anzeigen. So können Sie rechtzeitig reagieren, bevor Sie das Limit erreichen.

const RETRYABLE = new Set([429, 500, 502, 503, 504]);

async function synthWithRetry(text: string, voiceId: string, maxRetries = 5): Promise<Buffer> {
  let delay = 500; // ms, base for exponential backoff
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await elevenlabs.textToSpeech.convert(voiceId, {
        text, modelId: "eleven_flash_v2_5", outputFormat: "mp3_44100_128",
      });
    } catch (err: any) {
      const status = err.statusCode;
      // 401/422 and exhausted retries are not recoverable here.
      if (!RETRYABLE.has(status) || attempt === maxRetries) throw err;
      // Exponential backoff with full jitter.
      await new Promise((r) => setTimeout(r, Math.random() * delay));
      delay = Math.min(delay * 2, 8000);
    }
  }
  throw new Error("unreachable");
}

Wenn Sie mehr Puffer statt besserer Wiederholungslogik benötigen, upgraden Sie Ihren Tarif. Unternehmenskunden können höhere Limits über ihren Account Manager anfragen.

Latenz und Time-to-First-Byte messen

Die Latenz hängt von Ihrer Region, Ihrer Eingabe und der aktuellen Auslastung ab – der einzige verlässliche Wert ist der, den Sie selbst in Ihrer Umgebung messen.

In diesem Abschnitt erhalten Sie Time-to-First-Byte (TTFB) für den Flash-Streaming-Endpunkt. Die Struktur erlaubt es, denselben Test auch auf andere Anbieter anzuwenden und unter identischen Bedingungen zu vergleichen.

Verstehen Sie dies als Methodik, nicht als veröffentlichtes Ergebnis. Kein einzelner Durchlauf ist eine Garantie.

Wichtige Hinweise für das Benchmarking der Latenz einer Text to Speech API-Integration:

• Berücksichtigen Sie den Netzwerk-Roundtrip: TTFB hängt von Ihrer Geografie und dem nächstgelegenen Cluster des Anbieters ab. Führen Sie den Test dort aus, wo Ihre Server typischerweise laufen.
• Verwerfen Sie einen Warmup-Lauf: Die erste Anfrage an eine kalte Verbindung ist langsamer und kann die Werte verfälschen.
• Halten Sie die Eingaben konstant: Eingabelänge, Stimme, Modell und Auslastung beeinflussen das Ergebnis. Halten Sie diese Werte bei allen Anbietern identisch.
• Veröffentlichen Sie eine Verteilung: Die Werte schwanken von Lauf zu Lauf. Veröffentlichen Sie Median und p95 statt eines Einzelwerts.

Mit diesen Punkten sind Sie bereit für das Benchmarking.

const TEXT = "This is a fixed benchmark sentence used for every provider.";

async function measureElevenLabs(): Promise<number> {
  const start = performance.now();
  const res = await fetch(
    "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb/stream?output_format=mp3_44100_128",
    {
      method: "POST",
      headers: { "xi-api-key": process.env.ELEVENLABS_API_KEY!, "Content-Type": "application/json" },
      body: JSON.stringify({ text: TEXT, model_id: "eleven_flash_v2_5" }),
    },
  );
  for await (const _ of res.body!) {
    return performance.now() - start; // first chunk received
  }
  throw new Error("no audio returned");
}

Zum Vergleich mit einem anderen Anbieter schreiben Sie eine Funktion mit gleichem Aufbau. Führen Sie beide über ein kleines Testskript, das einen Warmup-Aufruf verwirft, etwa 20 zeitlich versetzte Messungen nimmt und Median sowie p95 in Millisekunden ausgibt.

Ein fairer Vergleich hängt davon ab, die Variablen zu kontrollieren.

Führen Sie beide Anbieter auf derselben Maschine und im selben Netzwerk aus – idealerweise auf einem Server in Ihrer Zielregion, nicht auf einem Laptop im Heimnetz. Nutzen Sie denselben Eingabetext und halten Sie das Audio kurz, damit die Modell-Inferenz den Wert dominiert. Veröffentlichen Sie Median und p95 über viele Läufe, da Einzelmessungen rauschen.

Beachten Sie, dass TTFB über das öffentliche Internet 20–200ms Netzwerk-Roundtrip enthält, der nichts mit dem Modell zu tun hat. Wir betreiben Cluster in Nordamerika, Europa und Südostasien und routen zur jeweils nächsten Instanz. Platzieren Sie Ihren Testclient entsprechend, sonst messen Sie vor allem die Entfernung zum Rechenzentrum.

Wichtige Punkte für Ihre Text to Speech API-Integration

Eine produktive Text to Speech API-Integration hängt von wenigen, aber entscheidenden Entscheidungen ab.

Wenn Sie diese richtig treffen, passt der Rest:

• Modell passend zum Anwendungsfall wählen: Nutzen Sie Flash v2.5 für interaktive Anwendungen und ein hochauflösendes Modell wie Multilingual v2 oder Eleven v3 für Offline-Rendering, bei dem Latenz weniger wichtig ist.
• Streamen, wenn ein Nutzer wartet: Nutzen Sie HTTP-Streaming für bekannten Text und WebSocket für Agenten, damit Leerlaufzeiten nicht Ihr Parallelitätsbudget belasten.
• Parallelität an Ihr Tariflimit anpassen: Begrenzen Sie gleichzeitige Anfragen knapp unter Ihrem Tariflimit und cachen Sie anhand eines Hashs aller ausgabe-relevanten Parameter, damit dasselbe Audio nie doppelt abgerechnet wird.
• 429 und 5xx mit Backoff und Jitter wiederholen: Bei 429 und 5xx mit vollem Jitter zurückgehen und die Parallelitäts-Header beobachten, um zu sehen, wie nah Sie am Limit sind.
• Lange Texte an Satzgrenzen aufteilen: Teilen Sie innerhalb des Zeichenlimits jedes Modells an Satzgrenzen, damit die Prosodie erhalten bleibt.

Wenn Sie noch tiefer einsteigen möchten, sehen Sie sich das Streaming-How-to, das Audio-Streaming-Konzept, Authentifizierung und Single-Use-Tokens für die Client-Seite an.

Bauen Sie Ihre Text to Speech-Integration mit ElevenAPI

Nach diesem Leitfaden kennen Sie alle Muster für eine produktive Text to Speech API-Integration. Ob Streaming, Batching, Caching, Retries oder Benchmarking – Sie sind bereit für den Einsatz.

Starten Sie, indem Sie mehr über die Text to Speech API erfahren oder registrieren Sie sich, um Ihren ersten Aufruf mit ElevenAPI zu machen.

Text to Speech API-Integration FAQ