Speech to Text API-integration: Guide för utvecklare

En Speech to Text API låter utvecklare lägga till taligenkänning och transkribering direkt i sina appar. Men innan du kopplar in STT API behöver du fatta några arkitekturbeslut.

Vilket transkriberingsläge ska du använda? Hur hanterar du långa ljudfiler? Hur ser du till att produktnamn eller egennamn stavas rätt? Lite planering här gör stor skillnad för att skapa en skalbar Speech to Text API-integration i dina utvecklarappar.

Den här guiden täcker allt du behöver för en ElevenLabs Speech to Text API-integration, med tydliga kodexempel du kan klistra in direkt i produktion. Ha gärna ElevenLabs Snabbstart för Speech to Text och API-guide öppna i ett annat fönster som referens.

Sammanfattning

• Det finns två lägen för ElevenLabs Speech to Text: batch (för förinspelat ljud) och realtime (för live-ljud via WebSocket).
• Scribe v2 hanterar batch-transkribering på över 90 språk med talaridentifiering, nyckelord, entity detection, tidsstämplar på ordnivå och stöd för flera kanaler.
• Scribe v2 Realtime hanterar live-streaming med cirka 150 ms fördröjning och levererar delvisa transkript medan du pratar samt färdiga transkript när ett talavsnitt är klart.
• För filer över 8 minuter delar Scribe v2 automatiskt upp och transkriberar parallellt. För långa jobb, använd webhooks istället för att vänta på ett synkront svar.
• Nyckelord styr modellen mot specifika termer med hjälp av kontext – mer tillförlitligt än listor för produktnamn, tekniska termer eller ovanliga egennamn.

Speech to Text API-integration: Batch vs. realtime

Varje ElevenLabs STT API-integration börjar med ett arkitekturbeslut: batch eller realtime. Båda ger dig en kraftfull STT-modell, men valet påverkar allt från vilka funktioner du kan använda till fördröjningen från start till slut.

Så här skiljer sig de två lägena:

• Batch (Scribe v2): Tar en hel ljud- eller videofil, transkriberar den och returnerar hela transkriptet i ett enda svar. Stöder flest funktioner: upp till 1 000 nyckelord, upp till 32 talare, entity detection, multikanal och webhooks för asynkron leverans. Filer upp till 3 GB och 10 timmar stöds i standardläge.
• Realtid (Scribe v2 Realtime): Tar emot en live-ljudström via WebSocket och returnerar delvisa och färdiga transkript medan ljudet kommer in, med cirka 150 ms fördröjning. Stöder upp till 50 nyckelord och tidsstämplar på ordnivå. Passar för röstassistenter, live-textning eller appar där användaren pratar och väntar på svar.

Vi går igenom skillnaderna mer i detalj.

En enkel tumregel: använd batch när ljudet är klart innan transkriberingen startar och realtime när du transkriberar ljud i realtid.

När ska du välja Scribe v2 vs. Scribe v2 Realtime

Batch och realtime passar olika behov, så om du väljer fel från början kan det leda till merjobb senare.

Här ser du hur du matchar modell till användningsområde:

• Scribe v2 är rätt val när ljudet är klart innan bearbetningen börjar, till exempel mötesinspelningar, poddar, mediefiler eller allt du kör offline. Stöder hela funktionsuppsättningen inklusive diarization, entity detection och upp till 1 000 nyckelord.
• Scribe v2 Realtime är byggd för live-ljud. Den tar emot en WebSocket-ström och returnerar transkript medan ljudet kommer in, vilket passar för röstassistenter eller när appen behöver svara innan användaren pratat klart.

En sak att tänka på är att noggrannheten varierar mellan språk. Det är värt att kolla transkriberingsfelprocenten innan du bestämmer språkblandning. Scribe v2 publicerar Word Error Rate (WER) för alla 90+ språk.

Utmärkt noggrannhet (≤5% WER) gäller för stora europeiska språk, japanska, indonesiska, vietnamesiska med flera. Hög noggrannhet (5-10% WER) gäller hindi, bengali, mandarin, koreanska, georgiska med flera. Se kategorierna i dokumentationen om språkstöd för fullständig översikt.

Så sätter du upp ElevenLabs Speech to Text API

Det krävs bara två enkla steg för att komma igång. Först installerar du SDK:n. Sedan sparar du dina inloggningsuppgifter på ett säkert sätt.

Så här gör du båda innan du skickar din första transkriberingsförfrågan.

Installera SDK:n och spara din API-nyckel som en hanterad hemlighet med en .env-fil eller din plattforms secrets manager. Hårdkoda aldrig din API-nyckel i appen.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js

Skapa en .env-fil:

ELEVENLABS_API_KEY=<your_api_key_here>

Initiera klienten:

Python

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

TypeScript

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

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

Din första batch-transkribering med ElevenLabs STT API

Nu när du har initierat klienten är du redo att skicka din första fil.

Batch-API:t tar en fil, transkriberar den och returnerar hela resultatet direkt. Exemplet nedan transkriberar en fjärr-ljudfil med talaridentifiering och ljudhändelser aktiverade.

Python

# example.py
import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",          # Model to use
    tag_audio_events=True,          # Tag audio events like laughter, applause, etc.
    language_code="eng",            # Language of the audio file. If set to None, the model will detect the language automatically.
    diarize=True,                   # Whether to annotate who is speaking
)

print(transcription)

Kör så här:

python example.py

Svaret innehåller hela transkriptet, ordposter med tidsstämplar och talar-ID samt upptäckta ljudhändelser.

Varje ordpost har ett type-fält med ett av tre värden:

• ord: För transkriberade ord i ljudet.
• mellanrum: Mellanrum mellan ord i språk som använder mellanslag. Gäller inte för vissa språk, som japanska, kantonesiska och burmesiska.
• audio_event: En tagg för icke-tal-ljud, som skratt eller hosta.

Så här ser svarstrukturen ut:

{
  "language_code": "en",
  "language_probability": 1,
  "text": "With a soft and whispery American accent, I'm the ideal choice for creating ASMR content, meditative guides, or adding an intimate feel to your narrative projects.",
  "words": [
    {
      "text": "With",
      "start": 0.119,
      "end": 0.259,
      "type": "word",
      "speaker_id": "speaker_0"
    },
    {
      "text": " ",
      "start": 0.239,
      "end": 0.299,
      "type": "spacing",
      "speaker_id": "speaker_0"
    },
    {
      "text": "a",
      "start": 0.279,
      "end": 0.359,
      "type": "word",
      "speaker_id": "speaker_0"
    }
  ]
}

Fältet language_probability visar hur säker modellen är på språkigenkänningen, på en skala från 0,00 till 1,00.

STT API Realtime-integration

Realtids-STT API-integration fungerar lite annorlunda. Istället för en förfrågan och ett svar öppnar du en WebSocket-anslutning och läser transkript medan de kommer in.

Realtime-API:t använder WebSocket för att ta emot en live-ljudström och returnera transkript medan ljudet kommer in. Det levererar två typer av transkript:

• Delvisa transkript: Mellanresultat som uppdateras medan modellen bearbetar inkommande ljud. Dessa kan ändras.
• Färdiga transkript: Slutgiltiga resultat för ett avslutat talavsnitt. Dessa ändras inte. De kan också innehålla tidsstämplar på ordnivå om du sätter "include timestamps" till true.

Klientimplementeringen använder en engångstoken istället för din API-nyckel direkt. Det är en tillfällig inloggning som går ut efter 15 minuter och genereras på serversidan så att din API-nyckel aldrig exponeras i webbläsaren.

Steg 1: Skapa en engångstoken (serversidan)

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

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

app.get("/scribe-token", yourAuthMiddleware, async (req, res) => {
  const token = await elevenlabs.tokens.singleUse.create("realtime_scribe");

  res.json(token);
});

Steg 2: Anslut och transkribera (klientsidan, React)

import { useScribe } from "@elevenlabs/react";

function MyComponent() {
  const scribe = useScribe({
    modelId: "scribe_v2_realtime",
    onPartialTranscript: (data) => {
      console.log("Partial:", data.text);
    },
    onCommittedTranscript: (data) => {
      console.log("Committed:", data.text);
    },
    onCommittedTranscriptWithTimestamps: (data) => {
      console.log("Committed with timestamps:", data.text);
      console.log("Timestamps:", data.words);
    },
  });

  const handleStart = async () => {
    // Fetch a single use token from the server
    const token = await fetchTokenFromServer();

    await scribe.connect({
      token,
      microphone: {
        echoCancellation: true,
        noiseSuppression: true,
      },
    });
  };

  return (
    <div>
      <button onClick={handleStart} disabled={scribe.isConnected}>
        Start Recording
      </button>
      <button onClick={scribe.disconnect} disabled={!scribe.isConnected}>
        Stop
      </button>

      {scribe.partialTranscript && <p>Live: {scribe.partialTranscript}</p>}

      <div>
        {scribe.committedTranscripts.map((t) => (
          <p key={t.id}>{t.text}</p>
        ))}
      </div>
    </div>
  );
}

Hooken useScribe hanterar WebSocket-anslutningen, mikrofonåtkomst och transkriptstatus. partialTranscript innehåller aktuell text; committedTranscripts är en växande lista med färdiga segment.

För streaming på serversidan (transkribera ljud från URL eller filström istället för mikrofon), se guiden för server-side streaming.

Parallellisering och skalning av långa filer

Långa filer kräver en annan skalningsmodell än de flesta API:er. Det är bra att förstå innan du bygger kring det.

Parallellisering för batch-transkribering fungerar annorlunda än i de flesta API:er. Istället för att begränsa antalet samtidiga förfrågningar hanterar Scribe v2 långa filer genom att automatiskt dela upp och köra parallellt.

Filer över 8 minuter delas upp i segment och transkriberas samtidigt. Antalet samtidiga segment beräknas så här:

Concurrency = min(4, round_up(audio_duration_secs / 480))

Konkret:

• En 15-minutersfil använder parallellisering på 2
• En 120-minutersfil använder parallellisering på 4 (max)

Filer upp till 10 timmar och 3 GB stöds i standardläge. Obs: multikanal har lägre tidsgräns – se avsnittet om multikanaltranskribering nedan.

När det gäller format stöder STT API de vanligaste ljud- och videoformaten:

• Ljud: AAC, AIFF, OGG, MP3, OPUS, WAV, FLAC, M4A, WebM.
• Video: MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP.

Du kan skicka in en videofil direkt och få ett transkript av ljudspåret utan förbehandling.

Nyckelord (keyterm prompting)

Generella modeller missar ofta varumärken och tekniska termer. Nyckelord löser det.

Nyckelord styr modellen mot specifika ord eller fraser vid transkribering. Det är rätt verktyg när ditt ljud innehåller produktnamn, tekniska termer eller egennamn med ovanlig stavning.

En fördel med nyckelord är att de använder kontext, vilket gör dem mer tillförlitliga än en enkel lista. Om du anger "ElevenLabs" som nyckelord transkriberar modellen det rätt när talaren säger företagsnamnet. Utan detta kan modellen ändå skriva "Jag har jobbat på eleven labs i ett år" fel.

Utan nyckelord:

I work at eleven labs.

Med keyterms=["ElevenLabs"]:

I work at ElevenLabs.

Batch stöder upp till 1 000 nyckelord (50 tecken vardera). Realtime stöder upp till 50 nyckelord (20 tecken vardera).

Batch-transkribering med nyckelord

Python

import os
from dotenv import load_dotenv
from io import BytesIO
import requests
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

audio_url = (
    "https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/stt-keyterm-prompting.mp3"
)
response = requests.get(audio_url)
audio_data = BytesIO(response.content)

transcription = elevenlabs.speech_to_text.convert(
    file=audio_data,
    model_id="scribe_v2",
    # Keyterms to prompt the model with.
    # Up to 1,000 keyterms can be provided, with a maximum length of 50 characters each
    keyterms=["ElevenLabs"],
)

print(transcription)

Realtime-streaming med nyckelord

Skicka med nyckelord när du ansluter till realtime-WebSocket:

Python

connection = await elevenlabs.speech_to_text.realtime.connect(RealtimeUrlOptions(
    model_id="scribe_v2_realtime",
    keyterms=["ElevenLabs"],
))

Eller skicka dem som query-parametrar direkt i WebSocket-URL:en:

wss://api.elevenlabs.io/v1/speech-to-text/realtime?model_id=scribe_v2_realtime&keyterms=ElevenLabs&keyterms=AnotherTerm

Nyckelord innebär en extra kostnad. Se API-prissidan för detaljer.

Avancerade funktioner

Stegen ovan tar dig genom grunden i STT API, men det finns flera funktioner som förbättrar slutresultatet. Här är några avancerade funktioner du kan använda i din Speech to Text API:

• Talaridentifiering för att se vem som pratar
• No-verbatim-läge för renare transkript
• Entity detection för att flagga känslig data
• Multikanaltranskribering för separata ljudkanaler

Vi går igenom dessa mer i detalj.

Talaridentifiering (diarization)

Sätt diarize=True i din batch-förfrågan för att markera vem som pratar. Scribe v2 stöder upp till 32 talare. Varje ord i svaret har ett speaker_id-fält (t.ex. speaker_0, speaker_1) som du kan använda för att dela upp transkriptet per talare.

Diarization är användbart för mötestranskribering, intervjuer eller alla inspelningar med flera talare där det är viktigt att veta vem som säger vad.

No-verbatim-läge

När no_verbatim=True tar modellen bort utfyllnadsord, felsägningar och tvekanden från transkriptet. "Eh, M-mja vi borde, öh, ta alternativ A" blir "Vi borde ta alternativ A."

Det ger renare resultat för undertexter, sammanfattningar eller när läsbarhet är viktigare än att få med varje ljud. Finns för både batch (scribe_v2) och realtime (scribe_v2_realtime).

Entity detection och maskering

Scribe v2 kan upptäcka och märka entiteter i transkriptet, med exakta tidsstämplar för varje upptäckt. Kategorier inkluderar PII (namn, kortnummer, personnummer), PHI (medicinska tillstånd) och PCI (betalningsinformation) med flera. För hela listan, se dokumentationen om entity detection.

Detta är särskilt användbart för regelefterlevnad, så att du kan identifiera och automatiskt maskera känslig information innan du sparar eller visar transkriptet.

Entity detection innebär en extra kostnad på $0.070 (per timme) utöver grundpriset. Se API-prissidan för detaljer.

Multikanaltranskribering

När use_multi_channel=True transkriberas varje ljudkanal separat och får ett talar-ID baserat på kanalnummer. Upp till 5 kanaler stöds. Maximal filtid i multikanal är 1 timme.

Multikanal är användbart när du har separata ljudspår per talare – till exempel en telefoninspelning där varje deltagare har sin egen kanal. Det ger mer exakt talaridentifiering än diarization på en mixad fil.

Asynkron leverans med webhooks

Att poll:a efter resultat funkar i liten skala men skalar dåligt för långa filer eller hög belastning. Webhooks löser det genom att skicka resultatet till dig istället.

För långa filer eller högvolymstranskribering är det inte alltid praktiskt att vänta på ett synkront svar. Med webhooks kan du skicka en transkriberingsförfrågan och få resultatet till din endpoint när det är klart, utan att poll:a.

Så sätter du upp en webhook

I ElevenLabs dashboard, gå till Utvecklare > Webhooks, klicka på Skapa webhook och konfigurera:

• Namn: Skriv ett beskrivande och minnesvärt namn för din webhook.
• Callback-URL: Lägg till en publikt tillgänglig HTTPS-endpoint till webbhooken.
• Webhook-autentisering: Välj HMAC eller OAuth (valfritt men starkt rekommenderat för säkerhet).
• Händelser: Välj Transcription completed i listan.

Skicka in en transkribering med webhook-leverans

Python

from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()

elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)

def transcribe_with_webhook(audio_file):
    try:
        result = elevenlabs.speech_to_text.convert(
            file=audio_file,
            model_id="scribe_v2",
            webhook=True,
        )
        print(f"Transcription started: {result.request_id}")
        return result
    except Exception as e:
        print(f"Error starting transcription: {e}")
        raise e

När webhook=True returnerar förfrågan direkt utan transkriptet. Det färdiga transkriptet skickas till din endpoint som en POST när bearbetningen är klar.

Så implementerar du din webhook-endpoint

import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js';
import 'dotenv/config';
import express from 'express';

const elevenlabs = new ElevenLabsClient();
const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/speech-to-text', (req, res) => {
  try {
    const signature = req.headers['elevenlabs-signature'];
    const payload = JSON.stringify(req.body);
    let event;

    try {
      // Verify the webhook signature.
      event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET);
    } catch (error) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    if (event.type === 'speech_to_text.completed') {
      const { requestId, status, text, language_code } = event.data;

      console.log(`Transcription ${requestId} completed`);
      console.log(`Language: ${language_code}`);
      console.log(`Text: ${text}`);

      processTranscription(requestId, text, language_code);
    } else if (status === 'failed') {
      console.error(`Transcription ${requestId} failed`);
      handleTranscriptionError(requestId);
    }

    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

Struktur på webhook-payload

Din endpoint tar emot en POST med följande struktur:

{
  "type": "speech_to_text_transcription",
  "data": {
    "request_id": "some-request-id-123",
    "webhook_metadata": {},
    "transcription": {
      "language_code": "en",
      "language_probability": 0.98,
      "text": "Hello world!",
      "words": [
        {
          "text": "Hello",
          "start": 0.0,
          "end": 0.5,
          "type": "word",
          "speaker_id": "speaker_1"
        }
      ]
    }
  }
}

Bästa praxis för webhook-säkerhet

När du bygger med webhooks finns det några säkerhetsåtgärder du kan ta för att säkerställa att händelser levereras och hanteras korrekt.

• Verifiera webhook-signaturer: Verifiera alltid webhook-signaturer med elevenlabs.webhooks.constructEvent() för att bekräfta att de kommer från ElevenLabs.
• Använd HTTPS-endpoints: Webhook-URL:er måste använda HTTPS för att skydda data under överföring.
• Returnera rätt HTTP-statuskod: Returnera 200-299 för lyckad hantering, 400-499 för klientfel (dessa försöks inte igen) och 500-599 för serverfel (dessa försöks igen).
• Använd tunneling-verktyg för lokal utveckling: För lokal utveckling, använd ett tunneling-verktyg som ngrok för att exponera din lokala server med en publik HTTPS-URL.

Med dessa strategier kan du använda webhooks tryggt.

Viktiga saker att ta med för din Speech to Text API-integration

En produktionsklar Speech to Text API-integration handlar om några viktiga val.

Får du till dessa så löser sig resten:

• Välj läge efter användning: Använd batch (scribe_v2) när ljudet är klart innan bearbetningen börjar. Använd realtime (scribe_v2_realtime) när du behöver transkribera medan ljudet skapas, till exempel för agenter, röstassistenter eller live-textning.
• Använd nyckelord för bättre träffsäkerhet på specifika ord: Skicka in produktnamn, tekniska termer eller ovanliga egennamn som nyckelord. Modellen använder kontext för att tolka dem rätt utan att överanvända dem.
• Låt API:t hantera långa filer: Filer över 8 minuter delas automatiskt upp och körs parallellt, så du behöver inte dela upp dem själv. Filer upp till 10 timmar och 3 GB stöds i standardläge.
• Använd webhooks för asynkrona flöden: För långa jobb eller hög belastning, webhook=True låter dig skicka och gå vidare. Verifiera alltid signaturen på inkommande webhook-payload.
• Aktivera no-verbatim-läge för renare resultat: Om du gör undertexter, sammanfattningar eller NLP-bearbetning, tar no_verbatim=True bort utfyllnadsord och tvekanden automatiskt.
• Använd multikanal för separata ljudspår: Om din inspelning har en kanal per talare (callcenter-inspelningar, intervjuer) ger multikanaltranskribering mer exakt talaridentifiering än diarization på en mixad fil. Observera tidsgränsen på 1 timme i detta läge.

Vill du veta mer? Utforska hela API-referensen som startpunkt.

Bygg din Speech to Text-integration med ElevenAPI

Efter den här guiden har du allt du behöver för en produktionsklar Speech to Text API-integration. Med batch och realtime-transkribering, samt avancerade funktioner som nyckelord och asynkron leverans, är du redo att lansera din app med STT.

Kom igång genom att läsa mer om Speech to Text API eller skapa ett konto för att göra ditt första anrop med ElevenAPI redan idag.

Vanliga frågor om STT API-integration