Text to Speech API-integration: streaming, batchning, omförsök

Att integrera ett Text to Speech API är enkelt … efter några konkreta beslut: vilket överföringsläge du ska använda, hur du väljer modell och utdataformat, hur du streamar, hur du hanterar stora volymer utan att överskrida din samtidighetsgräns, hur du cachar och försöker igen så att du aldrig betalar för att generera samma ljud två gånger, och hur du jämför time-to-first-byte med en annan leverantör.

För att hjälpa dig med integreringen av Text to Speech API har vi gått igenom vart och ett av dessa arkitekturbeslut och vad du ska göra. Den här guiden hjälper dig att integrera ElevenLabs Text to Speech API och skala upp, med kodexempel som du kan klistra in i produktion för att komma igång.

För en grundlig genomgång av begreppen som nämns här, se våra guider om att förstå ljudstreaming, att optimera latens, och översikt över ElevenLabs modeller. 

Sammanfattning

• Det finns en endpoint för ElevenLabs Text to Speech API, som du kan använda på tre sätt: batchkonvertering, HTTP-streaming och stream-input via WebSocket.
• Via HTTP räknas varje pågående begäran mot din samtidighetsgräns, medan endast aktiv generering räknas via WebSocket.
• Begränsa parallelliteten till strax under gränsen för din plan och cacha en hash för varje parameter som påverkar resultatet, så att samma text aldrig debiteras två gånger.
• Försök igen vid 429 och 5xx med exponentiell backoff och full jitter för att minska belastningen innan du når samtidighetsgränsen.

Tre sätt att integrera Text to Speech API

Det finns en endpoint för Text to Speech, men hur du integrerar den påverkar latens, komplexitet och kostnad. 

Samma anrop, POST /v1/text-to-speech/{voice_id}, fungerar på tre sätt och varje alternativ passar för ett lite annorlunda användningsfall. Här är en genomgång av de tre sätten att integrera Text to Speech API:

• Batch (convert) är den enklaste integreringen: Du skickar en begäran och får ett ljudsvar tillbaka. Det är alternativet med lägst komplexitet och högst tid till första ljudet, eftersom hela klippet syntetiseras innan några byte returneras.
• HTTP-streaming (stream) använder samma begäran men delar upp svaret i delar: Du lägger till /stream i sökvägen, anropar stream-metoden och får ljudet som ett chunkat svar. Koden är nästan identisk, medan den upplevda latensen är mycket lägre.
• WebSocket (stream-input) håller anslutningen öppen: Du skickar text stegvis och får tillbaka ljuddelar löpande. Den är byggd för interaktiva agenter och för att föra en LLM:s utdata till tal medan tokens skapas, innan meningen är klar.

Streaming får inte modellen att generera ljud snabbare; inferenstiden är oförändrad. Det som ändras är när du får den första delen: den skickas innan hela klippet är färdigt, så användarens upplevda väntetid blir kortare även om det totala arbetet är detsamma.

Beslutstabell: batch, streaming eller WebSocket

När du väljer mellan de här tre metoderna finns det flera faktorer att ta hänsyn till.

Som snabbguide: välj batch för offlinerendering, HTTP-streaming för känd text som en användare väntar på och WebSocket för agenter och livekonvertering från LLM till tal. 

Tabellen nedan visar avvägningarna för de dimensioner som spelar roll i stor skala.

Via HTTP räknas varje pågående begäran, oavsett om du använder batch eller streaming, mot samtidighetsgränsen i din plan under hela dess varaktighet. Via WebSocket räknas bara tiden då modellen aktivt genererar ljud; en öppen men inaktiv socket kostar i stort sett inget.

För en kaskadkopplad röstagent som håller en anslutning öppen under ett helt samtal men bara genererar ljud under agentens turer, är skillnaden stor. Det är den främsta anledningen att använda WebSocket när du bygger agenter. Hela protokollet beskrivs i guiden för Text to Speech via WebSocket i realtid.

Välja modell och utdataformat

Två val avgör ljudet du får tillbaka från din TTS API-integrering. Först modellen, som styr kvalitet och hastighet. Sedan utdataformatet, som styr containerformat, bithastighet och samplingsfrekvens.

Om du gör rätt val från början faller resten på plats, exempelvis latens och kompatibilitet med telefoni.

Modeller

Vi erbjuder flera Text to Speech-modeller. De är inte rangordnade från bäst till sämst; var och en innebär olika avvägningar.

Observera att siffran ~75 ms avser modellinferens under representativa förhållanden, exklusive nätverks- och applikationslatens. Den ökar med längre indata och under belastning. Mät alltid från din egen applikation, inte utifrån ett benchmarkvärde.

Flash-modeller är mindre och använder mer aggressiva approximationer för att minska inferenstiden. Eleven v3 och Multilingual v2 är större modeller som lägger mer tid per tecken för att skapa ett mer detaljerat resultat. Det finns ingen inställning som ger dig kvaliteten från Eleven v3 med Flash-hastighet, eftersom kvaliteten kommer från den extra beräkningen.

För realtid eller agenter använder du eleven_flash_v2_5; det är alternativet med lägst latens och stöd för flera språk. För berättarröst, ljudböcker eller voice-over för marknadsföring använder du eleven_multilingual_v2 när du vill ha stabil, hög ljudkvalitet, eller eleven_v3 när du behöver maximal uttrycksfullhet och känslomässigt omfång. 

När uttalet är viktigt, till exempel för telefonnummer, datum eller valutor, bör du själv normalisera siffrorna i applikationen innan texten når API:et. Skriv ut den talade form du vill ha. 

När du normaliserar själv blir uttalet förutsägbart mellan modeller och du slipper förlita dig på modellspecifika standardvärden som kan ändras.

Utdataformat

Parametern output_format styr containerformatet, samplingsfrekvensen och bithastigheten för ljudet du får tillbaka. De värden du oftast använder är:

Röstinställningar

Följande inställningar styr hur det genererade talet levereras:

• Stability: Styr balansen mellan konsekvens och uttrycksfullhet. Lägre värden ger mer varierat och uttrycksfullt tal, medan högre värden ger ett jämnare och mer förutsägbart framförande.
• SimilarityBoost: Styr hur nära resultatet följer referensrösten.
• Style: Förstärker röstens naturliga talstil när värdet höjs.
• useSpeakerBoost: Ökar likheten med den ursprungliga talaren till priset av lite högre latens.
• Speed: Justerar taltempot runt standardvärdet 1.0.

Av dessa inställningar har Stability vanligtvis störst påverkan på den upplevda kvaliteten. Lägre värden ger ett mer uttrycksfullt men mindre konsekvent resultat, medan högre värden prioriterar konsekvens och förutsägbarhet.

När du väljer röst ger Flash tillsammans med en Instant Voice Clone eller en standardröst lägst latens. Professional Voice Clones låter utmärkt, men medför extra arbete vid varje generering som du bör ta med i beräkningen.

I den här guiden är exempelröstens id JBFqnCBsd6RMkjVDRZzb (George).

Streamingintegrering (HTTP och WebSocket)

I det här avsnittet går vi igenom den praktiska kärnan i en Text to Speech API-integrering. Vi täcker installation av SDK:t, hur du öppnar en stream och tar emot ljud när det kommer. HTTP passar för det mesta av uppspelningen på webben och i appar, medan WebSocket passar för agenter och liveutdata från LLM:er.

Båda alternativen förutsätter att du har initierat ElevenLabs-klienten nedan.

npm install @elevenlabs/elevenlabs-js

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

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

Streamingalternativet öppnar en stream och tar emot delar när de kommer. voiceId är det första positionsargumentet, följt av ett options-objekt med camelCase-nycklar (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 WebSocket-varianten ansluter du till wss://api.elevenlabs.io/v1/text-to-speech/{voice_id}/stream-input, skickar ett första meddelande med dina röstinställningar och ett inledande mellanslag, skickar sedan textmeddelanden när de blir tillgängliga och läser JSON-ramar vars audio-fält innehåller base64-kodade delar.

Batchning och samtidighetsgränser för hög genomströmning

Integrering med hög genomströmning styrs av samtidighet, alltså antalet begäranden som genererar ljud i samma ögonblick. Varje plan har en gräns per modellfamilj. 

Varje plan har en egen samtidighetsgräns:

• Free: 4 samtidiga Flash-begäranden.
• Starter: 6 samtidiga Flash-begäranden.
• Creator: 10 samtidiga Flash-begäranden.
• Pro: 20 samtidiga Flash-begäranden.
• Scale och Business: 30 samtidiga Flash-begäranden; Enterprise-gränser anpassas individuellt.

Gränserna för Multilingual v2 är ungefär hälften så höga som ovan.

En begränsad pool hanterar detta genom att sätta ett tak för hur många begäranden som körs samtidigt:

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

Sätt MAX_CONCURRENCY lite under gränsen för din plan i stället för exakt på den. Den marginalen tar hand om annan trafik som delar samma nyckel och håller dig under gränsen där ett 429-svar returneras.

Teckengränser och uppdelning av lång text

Varje modell begränsar antalet tecken den tar emot i en enskild begäran. Vid integrering för längre innehåll måste du dela upp texten och sammanfoga ljudet igen. 

Här är teckengränserna per begäran för varje modell:

• Flash v2.5: Tar emot upp till 40 000 tecken per begäran.
• Flash v2: Tar emot upp till 30 000 tecken per begäran.
• Multilingual v2: Tar emot upp till 10 000 tecken per begäran.
• Eleven v3: Tar emot upp till 5 000 tecken per begäran.

Allt längre än så måste delas upp i flera begäranden. Försök dela vid meningsgränser så att prosodin bevaras i skarven mellan delarna.

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

Generera delarna i ordning och sammanfoga ljudet. För längre berättarröst där varje del är oberoende fungerar de två delarna direkt ihop: skicka utdata från splitText till den begränsade poolen ovan och låt den sköta resten.

Cachning och idempotens

Text to Speech-resultat är tillräckligt deterministiska för att det ska vara slöseri att generera samma text igen med samma röst, modell och inställningar. Cacha resultatet med en hash av indata som påverkar ljudet som nyckel, och låt samma nyckel fungera som en idempotenstoken vid nya försök.

Så här gör du båda delarna.

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

Regeln som får detta att fungera är att varje parameter som ändrar ljudet måste ingå i nyckeln, inklusive outputFormat och röstinställningar. Rätt gjort fungerar samma nyckel också som en idempotenstoken. När en klient försöker igen med en begäran som redan lyckats returnerar du de cachade byten i stället för att generera på nytt.

Felhantering och hastighetsgränser (429)

En produktionsklient behöver nya försök med backoff och jitter, samt hantering som varierar efter statuskod, eftersom vissa fel är värda att försöka igen efter och andra inte. 

Tabellen nedan kopplar varje status till rätt åtgärd, och avsnittet förklarar varför ett 429 är en mjuk gräns snarare än en hård vägg.

Ett 429 är inte en hård vägg, och det hjälper att förstå mekanismen. När du överskrider samtidighetsgränsen köas begäranden först efter prioritet, vilket vanligtvis lägger till omkring 50 ms. Du får bara ett 429 om du fortfarande överskrider kapaciteten efter det. 

Svaret innehåller också headers för current-concurrent-requests och maximum-concurrent-requests som visar din aktuella marginal, så att du kan läsa dem och minska belastningen innan du når gränsen.

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

När du behöver mer marginal snarare än bättre beteende vid nya försök uppgraderar du din plan. Enterprise-kunder kan begära högre gränser via sin account manager.

Benchmarking av latens och time-to-first-byte

Latens beror på din region, dina indata och den aktuella belastningen. Därför är det enda latensvärde du kan förlita dig på ett som du själv har mätt i din miljö. 

Det här avsnittet visar hur du mäter time-to-first-byte (TTFB) för Flash-endpointen för streaming. Strukturen gör att du kan rikta samma testverktyg mot en annan leverantör och jämföra dem under identiska förhållanden.

Se detta som en metod, inte som ett publicerat resultat. En enskild körning garanterar ingenting. 

Här är några viktiga förbehåll när du benchmarkar latensen i en Text to Speech API-integrering:

• Ta med nätverkets tur- och returtid: TTFB beror på var du befinner dig geografiskt och leverantörens närmaste kluster, så kör testet från den plats där dina servrar vanligtvis körs.
• Bortse från en uppvärmningskörning: Den första begäran över en kall anslutning är långsammare och kan snedvrida dina siffror.
• Håll indata konstanta: Indatalängd, röst, modell och belastning påverkar alla resultatet, så håll dem identiska mellan leverantörer.
• Redovisa en fördelning: Siffrorna varierar mellan körningar, så publicera medianen och p95 i stället för ett enda värde.

Med detta i åtanke är du redo att benchmarka.

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

För att jämföra med en annan leverantör skriver du en funktion med samma struktur. Kör sedan båda genom ett litet program som bortser från ett uppvärmningsanrop, tar cirka 20 tidsmätta prover med mellanrum så att de inte kolliderar med varandra och rapporterar medianen och p95 i millisekunder.

En rättvis jämförelse handlar om att kontrollera variablerna. 

Kör båda leverantörerna från samma dator och nätverk, helst från en server i regionen där du faktiskt driftsätter, inte från en laptop på ett vanligt hemnätverk. Använd samma inmatningstext och håll ljudet kort så att modellinferensen, snarare än genereringslängden, dominerar värdet. Redovisa medianen och p95 över många körningar, eftersom en enskild mätning är brus. 

Tänk på att TTFB över det publika internet inkluderar 20–200 ms nätverkstid tur och retur som inte har med modellen att göra. Vi levererar från kluster i Nordamerika, Europa och Sydostasien och dirigerar till det närmaste. Placera därför din testklient nära rätt kluster, annars benchmarkar du främst avståndet till datacentret.

Viktigaste punkterna för din Text to Speech API-integrering

En produktionsklar Text to Speech API-integrering handlar om en handfull viktiga beslut.

Om du gör rätt här faller resten på plats:

• Välj modell efter uppgift: Använd Flash v2.5 för allt interaktivt och en modell med högre ljudkvalitet, som Multilingual v2 eller Eleven v3 för offlinerendering där latens spelar mindre roll.
• Streama när en användare väntar: Använd HTTP-streaming för känd text och WebSocket för agenter, så att inaktiv tid inte belastar din samtidighetsbudget.
• Begränsa parallelliteten till gränsen för din plan: Begränsa samtidiga begäranden till strax under gränsen för din plan och cacha en hash av varje parameter som påverkar resultatet, så att samma ljud aldrig debiteras två gånger.
• Försök igen vid 429 och 5xx med exponentiell backoff och full jitter: Minska belastningen vid 429 och 5xx med full jitter, och bevaka headers för samtidighet för att se hur nära gränsen du är.
• Dela lång text vid meningsgränser: Dela vid meningsgränser inom varje modells teckengräns så att prosodin bevaras i skarven.

Om du vill gå ännu djupare kan du läsa guiden för streaming, begreppet ljudstreaming, autentisering, och engångstoken för användning på klientsidan.

Bygg din Text to Speech-integrering med ElevenAPI

Efter att ha läst den här guiden har du alla mönster du behöver för en produktionsklar Text to Speech API-integrering. Med streaming, batchning, cachning, nya försök och till och med benchmarking är du redo att omsätta detta i praktiken. 

Kom igång genom att läsa mer om Text to Speech API eller registrera dig för att göra ditt första anrop med ElevenAPI i dag.

Vanliga frågor om integrering av Text to Speech API