Integrazione Speech to Text API: Guida per sviluppatori

Una Speech to Text API permette agli sviluppatori di integrare funzionalità di riconoscimento e trascrizione vocale direttamente nelle proprie applicazioni. Prima di collegare la STT API, però, è necessario prendere alcune decisioni architetturali.

Quale modalità di trascrizione userai? Come gestirai i file audio lunghi? E come farai in modo che i nomi dei prodotti o i nomi propri vengano trascritti correttamente? Un po' di pianificazione qui fa la differenza per creare una soluzione scalabile di API Speech to Text nelle tue app per sviluppatori.

Questa guida copre tutto ciò che ti serve per integrare la Speech to Text API di ElevenLabs, con esempi di codice chiari che puoi incollare direttamente in produzione. Come riferimento, tieni aperti la guida rapida Speech to Text di ElevenLabs e la guida API in un'altra finestra.

Riepilogo

• Esistono due modalità Speech to Text di ElevenLabs: batch (per audio preregistrati) e realtime (per flussi audio live tramite WebSocket).
• Scribe v2 gestisce la trascrizione batch in oltre 90 lingue con diarizzazione dei parlanti, keyterm prompting, rilevamento entità, timestamp a livello di parola e supporto multicanale.
• Scribe v2 Realtime gestisce lo streaming live con una latenza di circa 150ms, fornendo trascrizioni parziali mentre parli e trascrizioni definitive quando termina un segmento di parlato.
• Per file superiori a 8 minuti, Scribe v2 suddivide e trascrive automaticamente in parallelo. Per lavori di lunga durata, usa i webhook invece di attendere la risposta sincrona.
• Il keyterm prompting indirizza il modello verso termini specifici usando il contesto: è più affidabile delle semplici liste di parole chiave per nomi di prodotti, termini tecnici o nomi propri insoliti.

Integrazione Speech to Text API: Batch vs. realtime

Ogni integrazione STT API di ElevenLabs parte da una scelta architetturale: batch o realtime. Entrambe ti permettono di integrare un modello STT potente nel tuo ambiente di sviluppo, ma questa scelta influisce su tutto, dalle funzionalità disponibili alla latenza end-to-end.

Ecco come si confrontano le due modalità:

• Batch (Scribe v2): Riceve un file audio o video completo, lo trascrive e restituisce la trascrizione completa in un'unica risposta. Supporta il set di funzionalità più ampio: fino a 1.000 keyterm, fino a 32 parlanti per la diarizzazione, rilevamento entità, modalità multicanale e webhook per la consegna asincrona. In modalità standard sono supportati file fino a 3 GB e 10 ore.
• Realtime (Scribe v2 Realtime): Accetta un flusso audio live tramite WebSocket e restituisce trascrizioni parziali e definitive man mano che arriva l'audio, con una latenza di circa 150ms. Supporta fino a 50 keyterm e timestamp a livello di parola, ed è la scelta giusta per assistenti vocali, sottotitoli live o qualsiasi applicazione in cui l'utente parla e si aspetta una risposta immediata.

Vediamo più nel dettaglio le differenze.

Regola pratica: usa batch quando l'audio è completo prima di iniziare la trascrizione e realtime quando trascrivi l'audio mentre viene prodotto.

Quando scegliere Scribe v2 o Scribe v2 Realtime

Batch e realtime coprono esigenze diverse, quindi scegliere la modalità sbagliata all'inizio può portare a dover rifare il lavoro dopo.

Per aiutarti nella scelta, ecco come abbinare il modello al tuo caso d'uso:

• Scribe v2 è la scelta giusta quando l'audio è completo prima dell'elaborazione, ad esempio per registrazioni di riunioni, trascrizione di podcast, file multimediali o qualsiasi cosa tu processi offline. Supporta tutte le funzionalità, inclusa la diarizzazione, il rilevamento entità e fino a 1.000 keyterm.
• Scribe v2 Realtime è pensato per l'audio live. Accetta un flusso WebSocket e restituisce le trascrizioni man mano che arriva l'audio, quindi è ideale per assistenti vocali o scenari in cui l'utente parla e la tua applicazione deve rispondere prima che finisca.

Un altro aspetto da considerare è che la precisione varia anche in base alla lingua. Vale la pena controllare il tasso di errore sulle parole prima di scegliere un mix di lingue. Scribe v2 pubblica i livelli di Word Error Rate (WER) per tutte le oltre 90 lingue supportate.

Precisione eccellente (≤5% WER) copre le principali lingue europee, giapponese, indonesiano, vietnamita e altre. Precisione alta (5-10% WER) copre hindi, bengalese, mandarino, coreano, georgiano e altre. Consulta la suddivisione per categoria nella documentazione sul supporto delle lingue per tutti i dettagli.

Configurare la Speech to Text API di ElevenLabs

Per avere un client funzionante bastano due semplici passaggi. Prima installa l’SDK. Poi conserva le tue credenziali in modo sicuro.

Ecco come fare entrambi i passaggi prima di inviare la tua prima richiesta di trascrizione.

Installa l’SDK e salva la tua API key come secret gestito usando un file .env o il secrets manager della tua piattaforma. Non inserire mai la tua API key direttamente nel codice.

Python

pip install elevenlabs
pip install python-dotenv

TypeScript

npm install @elevenlabs/elevenlabs-js

Crea un file .env:

ELEVENLABS_API_KEY=<your_api_key_here>

Inizializza il client:

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

La tua prima trascrizione batch con la STT API di ElevenLabs

Ora che hai inizializzato il client, sei pronto per inviare il tuo primo file.

La batch API riceve un file, lo trascrive e restituisce il risultato completo in modo sincrono. L’esempio qui sotto trascrive un file audio remoto con diarizzazione dei parlanti e tagging degli eventi audio attivi.

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)

Esegui:

python example.py

L’oggetto di risposta include il testo completo della trascrizione, le parole con timestamp e ID parlante, e gli eventi audio rilevati.

Ogni parola contiene un campo type con uno di questi tre valori:

• parola: Per le parole trascritte presenti nell’audio.
• spaziatura: Gli spazi tra le parole nelle lingue che li usano. Questo tipo non si applica a diverse lingue, come giapponese, cantonese e birmano.
• audio_event: Un tag per suoni non vocali, come una risata o un colpo di tosse.

Ecco come si presenta la struttura della risposta:

{
  "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"
    }
  ]
}

Il campo language_probability indica quanto il modello è sicuro di aver rilevato la lingua corretta, con un punteggio da 0,00 a 1,00.

Integrazione STT API Realtime

STT Realtime segue uno schema leggermente diverso. Invece di una richiesta e una risposta, apri una connessione WebSocket e leggi le trascrizioni man mano che arrivano.

La realtime API usa un WebSocket per ricevere un flusso audio live e restituire le trascrizioni in tempo reale. Fornisce due tipi di trascrizione:

• Trascrizioni parziali: Risultati intermedi che si aggiornano mentre il modello elabora l’audio in arrivo. Possono cambiare.
• Trascrizioni definitive: Risultati finali per un segmento di parlato completato. Non cambieranno più. Possono includere anche i timestamp a livello di parola se imposti l’opzione "include timestamps" su true.

L’implementazione lato client usa un token monouso invece della tua API key. Si tratta di una credenziale temporanea che scade dopo 15 minuti, generata lato server così la tua API key non viene mai esposta al browser.

Passaggio 1: Genera un token monouso (lato server)

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

Passaggio 2: Connetti e trascrivi (lato client, 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>
  );
}

L’hook useScribe gestisce il ciclo di vita della connessione WebSocket, l’accesso al microfono e lo stato delle trascrizioni. partialTranscript contiene il testo in corso; committedTranscripts è l’array crescente dei segmenti finalizzati.

Per lo streaming lato server (trascrizione da URL o stream di file invece che da microfono), consulta la guida allo streaming lato server.

Concorrenza e scalabilità per file lunghi

I file lunghi richiedono un modello di scalabilità diverso rispetto a quello usato dalla maggior parte delle API. È utile capirlo prima di costruirci sopra.

La concorrenza per la trascrizione batch funziona in modo diverso rispetto a molte API. Invece di limitare il numero di richieste simultanee, Scribe v2 gestisce i file lunghi parallelizzando automaticamente al suo interno.

I file superiori a 8 minuti vengono suddivisi in segmenti e trascritti in parallelo. Il numero di segmenti concorrenti viene calcolato così:

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

In pratica:

• Un file di 15 minuti usa una concorrenza di 2
• Un file di 120 minuti usa una concorrenza di 4 (il massimo)

Sono supportati file fino a 10 ore e 3 GB in modalità standard. Nota: la modalità multicanale ha un limite di durata inferiore - vedi la sezione sulla trascrizione multicanale qui sotto.

Per quanto riguarda i formati supportati, la STT API accetta i formati audio e video più comuni:

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

Puoi inviare direttamente un file video e ricevere la trascrizione della sua traccia audio senza alcuna elaborazione preventiva.

Suggerimento di parole chiave

I modelli generici tendono a trascrivere male nomi di brand e termini tecnici. Il keyterm prompting serve proprio a risolvere questo problema.

Il keyterm prompting indirizza il modello verso parole o frasi specifiche durante la trascrizione. È lo strumento giusto quando l’audio contiene nomi di prodotti, termini tecnici o nomi propri con ortografie insolite.

Un vantaggio del keyterm prompting è che usa il contesto, risultando più affidabile di una semplice lista di parole chiave. Se inserisci "ElevenLabs" come keyterm, il modello lo trascriverà correttamente quando il parlante nomina l’azienda. Senza questo, potresti trovare trascrizioni errate come "Ho lavorato a eleven labs per un anno".

Senza keyterm prompting:

I work at eleven labs.

Con keyterms=["ElevenLabs"]:

I work at ElevenLabs.

La modalità batch supporta fino a 1.000 keyterm (50 caratteri ciascuno). La modalità realtime supporta fino a 50 keyterm (20 caratteri ciascuno).

Trascrizione batch con keyterm

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)

Streaming realtime con keyterm

Passa i keyterm quando ti connetti al WebSocket realtime:

Python

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

Oppure passali come query parameter direttamente nell’URL del WebSocket:

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

Il keyterm prompting ha un costo aggiuntivo. Consulta la pagina prezzi API per i dettagli.

Funzionalità avanzate

Le procedure sopra descritte coprono il flusso base di trascrizione con la STT API, ma ci sono diverse funzionalità che arricchiscono il risultato finale. Ecco alcune funzioni avanzate che puoi usare nella tua Speech to Text API:

• Diarizzazione dei parlanti per identificare chi sta parlando
• Modalità no-verbatim per pulire le trascrizioni
• Rilevamento entità per segnalare dati sensibili
• Trascrizione multicanale per separare le tracce audio

Vediamole più nel dettaglio.

Diarizzazione dei parlanti

Imposta diarize=True nella richiesta batch per annotare chi sta parlando. Scribe v2 supporta fino a 32 parlanti. Ogni parola nella risposta include un campo speaker_id (es. speaker_0, speaker_1) che puoi usare per separare i segmenti di trascrizione per parlante.

La diarizzazione è utile per trascrivere riunioni, interviste o qualsiasi registrazione con più parlanti in cui è importante attribuire le parole alla persona giusta.

Modalità no-verbatim

Quando no_verbatim=True, il modello rimuove intercalari, esitazioni e disfluenze dalla trascrizione. "Ehm, F-forse dovremmo, eh, scegliere l’opzione A" diventa "Forse dovremmo scegliere l’opzione A."

Questo produce risultati più puliti per sottotitoli, riassunti o qualsiasi caso in cui la leggibilità conta più della fedeltà a ogni suono pronunciato. È disponibile sia per batch (scribe_v2) che per realtime (scribe_v2_realtime).

Rilevamento e oscuramento delle entità

Scribe v2 può rilevare e etichettare entità nella trascrizione, con timestamp precisi per ciascuna. Le categorie includono PII (nomi, numeri di carte di credito, SSN), PHI (condizioni mediche) e PCI (informazioni di pagamento), tra le altre. Per l’elenco completo delle entità supportate, consulta la documentazione sul rilevamento entità.

Questa funzione è particolarmente utile per esigenze di conformità, permettendoti di identificare e oscurare automaticamente informazioni sensibili prima di salvare o mostrare la trascrizione.

Il rilevamento entità ha un costo aggiuntivo di $0,070 (all’ora) sul costo base della trascrizione. Consulta la pagina prezzi API per i dettagli.

Trascrizione multicanale

Quando imposti use_multi_channel=True, ogni canale audio viene trascritto in modo indipendente e viene assegnato un ID parlante in base al numero di canale. Sono supportati fino a 5 canali. La durata massima dei file in modalità multicanale è di 1 ora.

La modalità multicanale è utile quando hai tracce audio separate per ogni parlante, ad esempio una registrazione di una chiamata in cui ogni partecipante è su un canale diverso. Questo permette un’attribuzione dei parlanti più precisa rispetto alla diarizzazione su un file mono mixato.

Consegna asincrona con webhook

Il polling del risultato va bene con pochi file, ma non scala quando inizi a lavorare con file lunghi o pipeline ad alto volume. I webhook risolvono questo problema inviandoti direttamente il risultato.

Per file lunghi o pipeline di trascrizione ad alto volume, aspettare la risposta sincrona non è sempre pratico. I webhook ti permettono di inviare la richiesta di trascrizione e ricevere il risultato sul tuo endpoint quando l’elaborazione è completata, senza polling.

Configurare un webhook

Nel dashboard di ElevenLabs, vai su Sviluppatori > Webhooks, clicca su Crea webhook e configura:

• Nome: Inserisci un nome descrittivo e facile da ricordare per il tuo webhook.
• URL di callback: Aggiungi un endpoint HTTPS pubblico al webhook.
• Metodo di autenticazione webhook: Seleziona HMAC o OAuth (opzionale ma fortemente consigliato per la sicurezza).
• Eventi: Seleziona Transcription completed tra le opzioni.

Invio di una trascrizione con consegna tramite webhook

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

Quando webhook=True, la richiesta restituisce subito senza la trascrizione. La trascrizione completata viene inviata al tuo endpoint come richiesta POST quando l’elaborazione è terminata.

Implementare il tuo endpoint webhook

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

Struttura del payload webhook

Il tuo endpoint riceve una POST con questa struttura:

{
  "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"
        }
      ]
    }
  }
}

Best practice di sicurezza per i webhook

Quando lavori con i webhook, ci sono alcune misure di sicurezza che puoi adottare per assicurarti che gli eventi vengano consegnati e processati correttamente.

• Verifica le firme dei webhook: Verifica sempre le firme dei webhook usando elevenlabs.webhooks.constructEvent() per confermare che provengano da ElevenLabs.
• Usa endpoint HTTPS: Gli URL dei webhook devono essere HTTPS per proteggere i dati in transito da manomissioni.
• Restituisci il codice di stato HTTP appropriato: Restituisci 200-299 per elaborazione riuscita, 400-499 per errori lato client (non verranno ritentati) e 500-599 per errori lato server (verranno ritentati).
• Usa uno strumento di tunneling per lo sviluppo locale: Per lo sviluppo locale, usa uno strumento di tunneling come ngrok per esporre il tuo server locale con un URL HTTPS pubblico.

Con queste strategie, puoi usare i webhook in tutta tranquillità.

Punti chiave per la tua integrazione Speech to Text API

Un’integrazione Speech to Text API pronta per la produzione si basa su poche decisioni fondamentali.

Se scegli bene questi aspetti, tutto il resto sarà più semplice:

• Scegli la modalità in base al caso d’uso: Usa batch (scribe_v2) quando l’audio è completo prima dell’elaborazione. Usa realtime (scribe_v2_realtime) quando devi trascrivere mentre l’audio viene prodotto, ad esempio per agent, assistenti vocali o sottotitoli live.
• Usa i keyterm per maggiore precisione su vocabolario specifico: Passa nomi di prodotti, termini tecnici o nomi propri insoliti come keyterm. Il modello usa il contesto per applicarli correttamente senza esagerare.
• Lascia che l’API gestisca i file lunghi: I file superiori a 8 minuti vengono parallelizzati automaticamente, quindi non serve suddividerli manualmente. Sono supportati file fino a 10 ore e 3 GB in modalità standard.
• Usa i webhook per pipeline asincrone: Per lavori lunghi o elaborazioni ad alto volume, webhook=True ti permette di inviare la richiesta e andare avanti. Verifica la firma su ogni payload webhook in arrivo.
• Attiva la modalità no-verbatim per risultati puliti: Se il tuo caso d’uso sono sottotitoli, riassunti o NLP a valle, no_verbatim=True rimuove automaticamente intercalari e disfluenze.
• Usa la modalità multicanale per tracce audio separate: Se la tua registrazione ha un canale per ogni parlante (registrazioni call center, interviste), la trascrizione multicanale permette un’attribuzione dei parlanti più precisa rispetto alla diarizzazione su un file mixato. Attenzione al limite di 1 ora in questa modalità.

Se vuoi approfondire, esplora il riferimento API completo come punto di partenza.

Crea la tua integrazione Speech to Text con ElevenAPI

Dopo aver letto questa guida, hai tutti gli schemi necessari per un’integrazione Speech to Text API pronta per la produzione. Tra trascrizione batch e realtime, e con funzionalità avanzate come keyterm prompting e consegna asincrona, sei pronto a lanciare la tua app con STT integrato.

Inizia scoprendo di più sulla API Speech to Text oppure registrati per effettuare la tua prima chiamata con ElevenAPI oggi stesso.

Domande frequenti sull’integrazione STT API