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

Die Integration einer Text to Speech API ist einfach – nachdem Sie einige konkrete Entscheidungen getroffen haben: Welchen Übertragungsmodus Sie nutzen, wie Sie Modell und Ausgabeformat wählen, wie Sie streamen, wie Sie hohe Volumen verarbeiten, ohne Ihr Parallelitätslimit zu überschreiten, wie Sie zwischenspeichern und Wiederholungen durchführen, damit Sie nie zweimal für dasselbe Audio zahlen, und wie Sie die Zeit bis zum ersten Byte mit einem anderen Anbieter vergleichen.

Um Sie bei der Integration einer Text to Speech API zu unterstützen, erläutern wir jede dieser Architekturentscheidungen und die jeweiligen Maßnahmen. Dieser Leitfaden hilft Ihnen bei der Integration der ElevenLabs Text to Speech API und beim Skalieren – mit Code-Snippets, die Sie direkt in Ihre Produktionsumgebung übernehmen können.

Ausführliche Hintergründe zu den hier genannten Konzepten finden Sie in unseren Leitfäden zu Audio-Streaming verstehen, Latenz optimieren und der ElevenLabs Modellübersicht. 

Zusammenfassung

• Es gibt einen ElevenLabs Text to Speech API-Endpunkt, den Sie auf drei Arten nutzen können: Batch-Konvertierung, HTTP-Stream und stream-input-WebSocket.
• Über HTTP zählt jede laufende Anfrage zu Ihrem Parallelitätslimit. Bei WebSocket zählt nur die aktive Generierung.
• Begrenzen Sie die Parallelität knapp unter Ihrem Planlimit und speichern Sie einen Hash aller Parameter, die die Ausgabe beeinflussen. So wird derselbe Text nie zweimal abgerechnet.
• Wiederholen Sie 429- und 5xx-Fehler mit exponentiellem Backoff und Full Jitter, um die Last zu reduzieren, bevor Sie das Parallelitätslimit erreichen.

Drei Wege zur Integration der Text to Speech API

Es gibt einen Text to Speech-Endpunkt, doch Ihre Integrationsmethode bestimmt Latenz, Komplexität und Kosten. 

Derselbe Aufruf POST /v1/text-to-speech/{voice_id} funktioniert in drei Varianten, die jeweils für leicht unterschiedliche Aufgaben geeignet sind. Hier sind alle drei Wege zur Integration der Text to Speech API:

• Batch (convert) ist die einfachste Integration: Sie senden eine Anfrage und erhalten eine Audioantwort. Dies ist die Option mit der geringsten Komplexität und der höchsten Zeit bis zum ersten Audio, da der gesamte Clip synthetisiert wird, bevor Daten zurückkommen.
• HTTP-Streaming (stream) verwendet dieselbe Anfrage, teilt die Antwort aber in Chunks auf: Sie ergänzen /stream im Pfad, rufen die stream-Methode auf und erhalten das Audio als gechunkte Antwort. Der Code ist fast identisch, die wahrgenommene Latenz jedoch deutlich niedriger.
• Der WebSocket (stream-input) hält eine persistente Verbindung: Sie senden Text schrittweise und erhalten parallel Audio-Chunks. Er ist für interaktive Agents und dafür ausgelegt, die Ausgabe eines LLM während der Token-Generierung in Sprache umzuwandeln – noch bevor der Satz fertig ist.

Streaming lässt das Modell Audio nicht schneller generieren; die Inferenzzeit bleibt unverändert. Streaming verändert, wann Sie den ersten Chunk erhalten: Er wird gesendet, bevor der gesamte Clip fertig ist. Dadurch verkürzt sich die wahrgenommene Wartezeit, 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 Kurzregel: Nutzen Sie Batch für Offline-Rendering, HTTP-Streaming für bekannten Text, auf den ein Nutzer wartet, und WebSocket für Agents sowie Live-LLM-zu-Sprache. 

Die folgende Tabelle zeigt die Abwägungen in den Dimensionen, die bei der Skalierung relevant sind.

Über HTTP zählt jede laufende Anfrage – ob Batch oder Streaming – während ihrer gesamten Dauer zu Ihrem Parallelitätslimit. Bei WebSocket zählt nur die Zeit, in der das Modell aktiv Audio generiert; ein offener, aber inaktiver Socket verursacht nahezu keine Kosten.

Bei einem kaskadierten Voice Agent, der eine Verbindung während eines ganzen Gesprächs offen hält, aber nur während der Sprechphasen des Agents Audio generiert, ist dieser Unterschied erheblich. Das ist der Hauptgrund, beim Entwickeln von Agents WebSockets zu nutzen. Das vollständige Protokoll ist im Leitfaden für Echtzeit-Text-to-Speech-WebSockets dokumentiert.

Modell und Ausgabeformat wählen

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

Wenn Sie beides von Beginn an richtig wählen, stimmen auch nachgelagerte Faktoren wie Latenz und Telefoniekompatibilität.

Modelle

Wir bieten mehrere Text to Speech-Modelle an. Sie sind nicht von besten bis schlechtesten eingestuft; jedes trifft andere Abwägungen.

Hinweis: Der Wert von etwa 75 ms bezeichnet die Modellinferenz unter repräsentativen Bedingungen, ohne Netzwerk- und Anwendungslatenz. Bei längeren Eingaben und unter Last steigt er. Messen Sie immer in Ihrer Anwendung, nicht anhand eines Benchmark-Werts.

Flash-Modelle sind kleiner und nutzen stärkere Approximationen, um die Inferenzzeit zu reduzieren. Eleven v3 und Multilingual v2 sind größere Modelle, die mehr Zeit pro Zeichen für eine reichhaltigere Ausgabe aufwenden. Es gibt keine Einstellung, die Ihnen die Qualität von Eleven v3 bei Flash-Geschwindigkeit bietet, da diese Qualität zusätzliche Berechnungen erfordert.

Für Echtzeit- oder Agent-Anwendungen verwenden Sie eleven_flash_v2_5; es ist die mehrsprachige Option mit der geringsten Latenz. Für Erzählungen, Hörbücher oder Marketing-Voiceovers verwenden Sie eleven_multilingual_v2 für stabile, hohe Klangtreue oder eleven_v3 für maximale Ausdruckskraft und emotionale Bandbreite. 

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

Eine eigene Normalisierung sorgt für eine modellübergreifend vorhersehbare Aussprache und verhindert Abhängigkeiten von modellspezifischen Standardwerten, die sich ändern können.

Ausgabeformat

Der Parameter output_format steuert Container, Samplingrate und Bitrate des zurückgegebenen Audios. Am häufigsten werden Sie folgende Werte verwenden:

Stimmeinstellungen

Die folgenden Einstellungen steuern, wie die generierte Sprache ausgegeben wird:

• Stability: Steuert das Verhältnis zwischen Konsistenz und Ausdruckskraft. Niedrigere Werte erzeugen variablere, ausdrucksstärkere Sprache, höhere Werte eine gleichmäßigere, vorhersehbarere Wiedergabe.
• SimilarityBoost: Steuert, wie eng die Ausgabe der Referenzstimme folgt.
• Style: Verstärkt bei höheren Werten den natürlichen Sprechstil der Stimme.
• useSpeakerBoost: Erhöht die Ähnlichkeit mit dem ursprünglichen Sprecher bei leicht höherer Latenz.
• Speed: Passt das Sprechtempo um den Standardwert 1.0 an.

Von diesen Einstellungen hat Stability in der Regel den größten Einfluss auf die wahrgenommene Qualität. Niedrigere Werte erzeugen ausdrucksstärkere, aber weniger konsistente Ausgaben, während höhere Werte Konsistenz und Vorhersehbarkeit priorisieren.

Bei der Stimmwahl bietet Flash in Kombination mit einem Instant Voice Clone oder einer Standardstimme die niedrigste Latenz. Professional Voice Clones klingen hervorragend, verursachen jedoch zusätzlichen Aufwand pro Generierung, den Sie einplanen sollten.

In diesem Leitfaden verwenden wir die Beispiel-Stimm-ID JBFqnCBsd6RMkjVDRZzb (George).

Streaming-Integration (HTTP und WebSocket)

In diesem Abschnitt behandeln wir den praktischen Kern der Text to Speech API-Integration: die SDK-Installation, das Öffnen eines Streams und die Verarbeitung eingehender Audiodaten. Der HTTP-Pfad deckt die meisten Wiedergaben im Web und in Apps ab, der WebSocket-Pfad Agents und Live-LLM-Ausgaben.

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

npm install @elevenlabs/elevenlabs-js

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

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

Der Streaming-Pfad öffnet einen Stream und verarbeitet Chunks, sobald sie eintreffen. voiceId ist das erste Positionsargument, gefolgt von einem Optionsobjekt 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 zunächst eine Nachricht mit Ihren Stimmeinstellungen und einem führenden Leerzeichen, senden dann Textnachrichten, sobald sie verfügbar sind, und lesen JSON-Frames zurück, deren audio-Feld Base64-kodierte Chunks enthält.

Batching und Parallelitätslimits für hohen Durchsatz

Integrationen mit hohem Durchsatz werden durch die Parallelität bestimmt: die Anzahl der Anfragen, die im selben Moment Audio generieren. Jeder Plan hat ein Limit pro Modellfamilie. 

Jeder Plan 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 sind individuell.

Die Limits für Multilingual v2 liegen bei etwa der Hälfte dieser Werte.

Ein begrenzter Pool löst dies, indem er die Anzahl gleichzeitig laufender Anfragen beschränkt:

// 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 niedriger als Ihr Planlimit, statt genau darauf. Dieser Puffer fängt weiteren Traffic ab, der denselben Schlüssel verwendet, und hält Sie unter der Schwelle, ab der ein 429 zurückgegeben wird.

Zeichenlimits und Aufteilen langer Texte

Jedes Modell begrenzt die Anzahl der Zeichen, die es in einer einzelnen Anfrage akzeptiert. Bei jeder Longform-Integration müssen Sie Text aufteilen und das Audio wieder zusammenfügen. 

Hier sind die Zeichenlimits pro Anfrage für jedes Modell:

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

Längere Texte müssen Sie in mehrere Anfragen aufteilen. Teilen Sie möglichst an Satzgrenzen, damit die Prosodie an den Übergängen zwischen Chunks 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;
}

Generieren Sie die Chunks in der richtigen Reihenfolge und verketten Sie das Audio. Bei langen Erzählungen, deren Chunks unabhängig sind, greifen die beiden Teile direkt ineinander: Geben Sie die Ausgabe von splitText in den begrenzten Pool oben und überlassen Sie ihm den Rest.

Caching und Idempotenz

Die Text to Speech-Ausgabe ist ausreichend deterministisch, sodass es verschwenderisch ist, denselben Text mit derselben Stimme, demselben Modell und denselben Einstellungen erneut zu generieren. Speichern Sie das Ergebnis anhand eines Hashs der Eingaben, die das Audio beeinflussen. Derselbe Schlüssel dient bei Wiederholungen auch als Idempotenz-Token.

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

Damit dies funktioniert, muss jeder Parameter, der das Audio verändert, im Schlüssel enthalten sein – einschließlich outputFormat und Stimmeinstellungen. Korrekt umgesetzt dient derselbe Schlüssel auch als Idempotenz-Token. Wiederholt ein Client eine bereits erfolgreiche Anfrage, geben Sie die zwischengespeicherten Bytes zurück, statt das Audio erneut zu generieren.

Fehlerbehandlung und Rate Limits (429)

Ein Produktionsclient benötigt Wiederholungen mit Backoff und Jitter sowie eine statuscodeabhängige Behandlung, denn manche Fehler lassen sich sinnvoll wiederholen und andere nicht. 

Die folgende Tabelle ordnet jedem Status die richtige Maßnahme zu. In diesem Abschnitt erfahren Sie zudem, warum ein 429 ein weiches Limit und keine harte Grenze ist.

Ein 429 ist keine harte Grenze. Der zugrunde liegende Mechanismus ist wichtig: Wenn Sie das Parallelitätslimit überschreiten, werden Anfragen zunächst nach Priorität in die Warteschlange gestellt, was typischerweise etwa 50 ms hinzufügt. Nur wenn die Kapazität danach weiterhin überschritten ist, erhalten Sie einen 429. 

Die Antwort enthält außerdem die Header current-concurrent-requests und maximum-concurrent-requests. Sie zeigen Ihren aktuell verfügbaren Puffer, sodass Sie die Last reduzieren können, 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 Kapazität statt eines besseren Wiederholungsverhaltens benötigen, wechseln Sie in einen höheren Plan. Enterprise-Kunden können über ihren Account Manager erhöhte Limits anfordern.

Latenz und Zeit bis zum ersten Byte benchmarken

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

Dieser Abschnitt behandelt Time-to-First-Byte (TTFB) für den Flash-Streaming-Endpunkt. Er ist so aufgebaut, dass Sie dasselbe Test-Harness auf einen anderen Anbieter richten und beide unter identischen Bedingungen vergleichen können.

Betrachten Sie dies als Methodik, nicht als veröffentlichtes Ergebnis. Ein einzelner Durchlauf garantiert nichts. 

Beim Benchmarking der Latenz einer Text to Speech API-Integration sind einige wichtige Punkte zu beachten:

• Netzwerk-Roundtrip einbeziehen: TTFB hängt von Ihrem Standort und dem nächstgelegenen Cluster des Anbieters ab. Führen Sie den Test daher dort aus, wo Ihre Server normalerweise laufen.
• Warm-up-Durchlauf verwerfen: Die erste Anfrage über eine kalte Verbindung ist langsamer und kann Ihre Werte verfälschen.
• Eingaben konstant halten: Eingabelänge, Stimme, Modell und Auslastung beeinflussen das Ergebnis. Halten Sie sie daher bei allen Anbietern identisch.
• Verteilung angeben: Die Werte variieren von Durchlauf zu Durchlauf. Veröffentlichen Sie daher Median und p95 statt eines einzelnen Werts.

Damit 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");
}

Um mit einem anderen Anbieter zu vergleichen, schreiben Sie eine Funktion mit derselben Struktur. Führen Sie dann beide mit einem kleinen Runner aus, der einen Warm-up-Aufruf verwirft, etwa 20 zeitlich getrennte Messungen vornimmt, damit sie sich nicht gegenseitig beeinflussen, und Median sowie p95 in Millisekunden ausgibt.

Ein fairer Vergleich hängt von kontrollierten Variablen ab. 

Führen Sie beide Anbieter von derselben Maschine und über dasselbe Netzwerk aus – idealerweise von einem Server in der Region, in der Sie tatsächlich bereitstellen, statt von einem Laptop über privates Breitband. Verwenden Sie denselben Eingabetext und halten Sie das Audio kurz, damit die Modellinferenz den Wert stärker bestimmt als die Generierungslänge. Geben Sie Median und p95 über viele Durchläufe an, denn eine einzelne Messung ist Rauschen. 

Beachten Sie, dass TTFB über das öffentliche Internet einen Netzwerk-Roundtrip von 20 bis 200 ms enthält, der nichts mit dem Modell zu tun hat. Wir betreiben Cluster in Nordamerika, Europa und Südostasien und leiten Anfragen zum nächstgelegenen weiter. Platzieren Sie Ihren Testclient entsprechend, sonst messen Sie hauptsächlich die Entfernung zum Rechenzentrum.

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

Eine produktionsreife Text to Speech API-Integration hängt von einer Handvoll wichtiger Entscheidungen ab.

Wenn Sie diese richtig treffen, fügt sich alles andere zusammen:

• Modell nach Aufgabe wählen: Nutzen Sie Flash v2.5 für alles Interaktive und ein Modell mit höherer Klangtreue wie Multilingual v2 oder Eleven v3 für Offline-Rendering, bei dem die Latenz weniger wichtig ist.
• Streamen, wenn Nutzer warten: Nutzen Sie HTTP-Streaming für bekannten Text und WebSocket für Agents, damit Leerlaufzeit Ihr Parallelitätsbudget nicht belastet.
• Parallelität auf Ihr Planlimit begrenzen: Begrenzen Sie gleichzeitige Anfragen knapp unter Ihrem Planlimit und cachen Sie anhand eines Hashs aller ausgaberelevanten Parameter, damit dasselbe Audio nie zweimal abgerechnet wird.
• 429 und 5xx mit exponentiellem Backoff und Full Jitter wiederholen: Reduzieren Sie bei 429 und 5xx mit Full Jitter die Last und überwachen Sie die Parallelitäts-Header, um zu sehen, wie nah Sie am Limit sind.
• Lange Texte an Satzgrenzen aufteilen: Teilen Sie an Satzgrenzen innerhalb des Zeichenlimits jedes Modells, damit die Prosodie an den Übergängen erhalten bleibt.

Wenn Sie noch tiefer einsteigen möchten, lesen Sie den Streaming-Leitfaden, das Konzept zu Audio-Streaming, Informationen zur Authentifizierung sowie zu Einmal-Tokens für die clientseitige Nutzung.

Ihre Text to Speech-Integration mit ElevenAPI entwickeln

Nach diesem Leitfaden kennen Sie alle Muster für eine produktionsreife Text to Speech API-Integration. Von Streaming, Batching und Caching über Wiederholungen bis zum Benchmarking: Sie sind bereit für den produktiven Einsatz. 

Starten Sie, indem Sie mehr über die Text to Speech API erfahren oder sich registrieren, um noch heute Ihren ersten Aufruf mit ElevenAPI auszuführen.

FAQ zur Text to Speech API-Integration