Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Trascrivere un file audio: gpt-transcribe e Whisper

Lezione 6 di 18 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Trascrivere una registrazione
  2. Quale modello a novembre 2026
  3. Prima trascrizione
  4. Fornire contesto al modello
  5. Seguire la trascrizione in tempo reale
  6. Timestamp e sottotitoli: whisper-1, fino al 26 febbraio 2027
  7. File lunghi
  8. Punti chiave

Lezione riscritta il 3 novembre 2026. Questa guida trattava in precedenza whisper-1, deprecato e che verrà disattivato il 26 febbraio 2027. La guida Trascrizione di file di OpenAI raccomanda ora gpt-transcribe. Tuttavia, gpt-transcribe non fornisce timestamp, sottotitoli SRT o VTT, né una risposta verbose_json. Per queste esigenze specifiche, whisper-1 rimane l’unica opzione fino alla sua disattivazione. Il codice precedente accedeva ai segmenti come dizionari (segment["start"]), il che genera un TypeError con l’SDK Python; sono oggetti (segment.start). Ogni chiamata è stata verificata con l’SDK openai 3.42.1. Fonti: Trascrizione di file · Crea trascrizione · GPT-Transcribe · Deprecazioni.

Trascrivere una registrazione

La trascrizione di file risponde al caso d’uso più comune: hai una registrazione conclusa (una riunione, un podcast, un messaggio vocale) e ti serve il testo. Invii il file all’endpoint /v1/audio/transcriptions e ricevi la trascrizione. Per l’audio che arriva ancora in tempo reale, ad esempio da un microfono o una chiamata, l’approccio corretto è la trascrizione live tramite le Realtime API, trattata più avanti in questo corso.

Il file deve essere di 25 MB o inferiore, in uno dei seguenti formati: mp3, mp4, mpeg, mpga, m4a, wav o webm.

Quale modello a novembre 2026

ModelloStatoPunti chiave
gpt-transcribeConsigliatoContesto (prompt), parole chiave (keywords), lingue attese (languages), trascrizione in streaming; 0,0045 $ al minuto
whisper-1Deprecato, disattivazione 26 febbraio 2027Unico modello che fornisce timestamp, verbose_json, SRT e VTT, e traduzione in inglese
gpt-4o-transcribe, gpt-4o-mini-transcribeDeprecato, disattivazione 26 febbraio 2027Sostituito da gpt-transcribe
gpt-4o-transcribe-diarizeDeprecato, disattivazione 26 febbraio 2027Identificazione degli speaker (diarized_json)

Prima trascrizione

from openai import OpenAI

client = OpenAI()

with open("recording.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
    )

print(transcription.text)

Per impostazione predefinita, la risposta è un oggetto JSON: transcription.text contiene il testo, mentre transcription.languages elenca le lingue che il modello ha riconosciuto con sufficiente confidenza (un elenco vuoto se non ne ha identificate).

Fornire contesto al modello

Una registrazione di una riunione è piena di nomi propri, acronimi e termini interni che il modello non ha motivo di conoscere. gpt-transcribe accetta tre suggerimenti che puoi combinare:

with open("meeting.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        prompt="Riunione di gestione sul progetto Corsen AI e contratto AC-42.",
        keywords=["Corsen AI", "AC-42", "GDPR"],
        languages=["fr", "en"],
    )

print(transcription.text)
  • prompt descrive il contesto in una singola frase, nella lingua della registrazione. Non è un’istruzione di sistema; è un suggerimento che guida il riconoscimento.
  • keywords elenca i termini da riconoscere. Inserisci una parola chiave per elemento, senza <, > o interruzioni di riga: l’API rifiuta l’intera richiesta se ne trova qualcuno.
  • languages specifica le lingue attese utilizzando i codici ISO 639-1 (fr, en, es…). Sostituisce il parametro language dei modelli precedenti: non inviarli mai entrambi.

Seguire la trascrizione in tempo reale

Per file lunghi, non è necessario attendere la fine per visualizzare l’inizio. Con stream=True, l’API restituisce eventi man mano che l’elaborazione avviene, senza richiedere una sessione Realtime:

with open("meeting.mp3", "rb") as audio_file:
    stream = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        stream=True,
    )
    for event in stream:
        if event.type == "transcript.text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "transcript.text.done":
            print()  # trascrizione completa in event.text

Timestamp e sottotitoli: whisper-1, fino al 26 febbraio 2027

La guida di OpenAI afferma esplicitamente: i suoi esempi per timestamp a livello di parola, sottotitoli e identificazione degli speaker si basano su modelli deprecati. Se hai bisogno di queste funzionalità, whisper-1 rimane disponibile fino al 26 febbraio 2027 ed è l’unico modello che accetta verbose_json e timestamp_granularities:

with open("meeting.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="whisper-1",
        file=audio_file,
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

for segment in transcription.segments or []:
    print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text.strip()}")

I segmenti sono oggetti SDK: leggi segment.start, non segment["start"]. Con timestamp_granularities=["word"], i timestamp a livello di parola appaiono in transcription.words, al costo di una latenza leggermente superiore. Lo stesso modello produce anche sottotitoli pronti all’uso: con response_format="srt" o "vtt", l’SDK restituisce direttamente il testo del file di sottotitoli.

La guida non indica ancora un sostituto per queste funzioni. Se il tuo prodotto dipende da timestamp o sottotitoli, pianifica una soluzione prima del 26 febbraio 2027.

File lunghi

Per file superiori a 25 MB, comprimi l’audio o dividilo. La documentazione raccomanda di evitare tagli nel mezzo di una frase, il che fa perdere contesto, e suggerisce la libreria pydub per la divisione (OpenAI non garantisce questo software di terze parti). Passare la fine del chunk precedente nel prompt aiuta il modello a mantenere la continuità, un uso del parametro citato nella guida:

from pydub import AudioSegment


def transcribe_long(path: str, duration_ms: int = 10 * 60 * 1000) -> str:
    """Trascrive una registrazione lunga in chunk da 10 minuti."""
    audio = AudioSegment.from_file(path)
    texts: list[str] = []

    for i, start in enumerate(range(0, len(audio), duration_ms)):
        chunk = f"chunk_{i}.mp3"
        audio[start:start + duration_ms].export(chunk, format="mp3")
        options = {"prompt": texts[-1][-500:]} if texts else {}  # continuità
        with open(chunk, "rb") as f:
            result = client.audio.transcriptions.create(model="gpt-transcribe", file=f, **options)
        texts.append(result.text)

    return " ".join(texts)

La divisione a durata fissa taglia talvolta una frase a metà: per un risultato rifinito, dividi invece sui silenzi.

Punti chiave

  • gpt-transcribe è il modello consigliato per la trascrizione di file; whisper-1 e gpt-4o-*-transcribe verranno disattivati il 26 febbraio 2027
  • prompt, keywords e languages (non più language) guidano il riconoscimento di termini e lingue
  • stream=True restituisce la trascrizione al volo (transcript.text.delta), senza una sessione Realtime
  • Timestamp, verbose_json, SRT e VTT esistono solo con whisper-1 fino alla sua disattivazione; leggi i segmenti come oggetti (segment.start)
  • Massimo 25 MB per file: comprimi o dividi, preferibilmente sui silenzi