Trascrivere un file audio: gpt-transcribe e Whisper
In questa pagina
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 oragpt-transcribe. Tuttavia,gpt-transcribenon fornisce timestamp, sottotitoli SRT o VTT, né una rispostaverbose_json. Per queste esigenze specifiche,whisper-1rimane l’unica opzione fino alla sua disattivazione. Il codice precedente accedeva ai segmenti come dizionari (segment["start"]), il che genera unTypeErrorcon l’SDK Python; sono oggetti (segment.start). Ogni chiamata è stata verificata con l’SDKopenai3.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
| Modello | Stato | Punti chiave |
|---|---|---|
gpt-transcribe | Consigliato | Contesto (prompt), parole chiave (keywords), lingue attese (languages), trascrizione in streaming; 0,0045 $ al minuto |
whisper-1 | Deprecato, disattivazione 26 febbraio 2027 | Unico modello che fornisce timestamp, verbose_json, SRT e VTT, e traduzione in inglese |
gpt-4o-transcribe, gpt-4o-mini-transcribe | Deprecato, disattivazione 26 febbraio 2027 | Sostituito da gpt-transcribe |
gpt-4o-transcribe-diarize | Deprecato, disattivazione 26 febbraio 2027 | Identificazione 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)
promptdescrive il contesto in una singola frase, nella lingua della registrazione. Non è un’istruzione di sistema; è un suggerimento che guida il riconoscimento.keywordselenca 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.languagesspecifica le lingue attese utilizzando i codici ISO 639-1 (fr,en,es…). Sostituisce il parametrolanguagedei 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-1egpt-4o-*-transcribeverranno disattivati il 26 febbraio 2027prompt,keywordselanguages(non piùlanguage) guidano il riconoscimento di termini e linguestream=Truerestituisce la trascrizione al volo (transcript.text.delta), senza una sessione Realtime- Timestamp,
verbose_json, SRT e VTT esistono solo conwhisper-1fino alla sua disattivazione; leggi i segmenti come oggetti (segment.start) - Massimo 25 MB per file: comprimi o dividi, preferibilmente sui silenzi