Whisper-1 API: prima trascrizione audio con Python

Una prima richiesta all’API Whisper-1 richiede un file audio, un ID del modello esplicito e un formato di output. Su SeedRouter carichi la registrazione, salvi l’ID dell’attività restituito e scarichi la trascrizione quando l’attività è completata. Inizia con una registrazione breve di cui conosci già le parole: sarà più facile notare parole mancanti e grafie insolite.

Questa guida segue il contratto asincrono di SeedRouter. Non è un esempio sincrono dell’SDK OpenAI utilizzabile senza modifiche. La pagina del modello Whisper-1 contiene il Playground e il prezzo attuale; il riferimento API elenca ogni campo e le verifiche di compatibilità ancora aperte. ^[1]

Prepara una registrazione

Usa parlato che hai il permesso di elaborare. Un breve WAV o MP3 è un buon punto di partenza. Il limite attuale di caricamento è 26.214.400 byte; il file deve contenere audio leggibile con durata misurabile. L’estensione .mp3 non rende valido un file di testo rinominato. Il riferimento distingue i nove formati di input documentati da quelli che hanno superato verifiche reali. ^[1]

La registrazione seguente è parlato sintetico originale in inglese, creato per questo tutorial. La sua forma d’onda compare sulla copertina. La frase citata sulla copertina viene dal copione della registrazione, non è un’affermazione di accuratezza.

Scarica il campione di 10,31 secondi. Il copione dice: “This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.”

Conserva una chiave API in una variabile d’ambiente lato server. Non inserirla in una pagina web pubblica, in un pacchetto di app mobile o in uno screenshot condiviso. L’esempio Python seguente usa requests e legge SEEDROUTER_API_KEY dall’ambiente.

Invia la richiesta API Whisper-1 una sola volta

Scegli json per una prima richiesta. Potrai leggere il campo text del risultato scaricato senza gestire i codici temporali dei sottotitoli. La parte multipart file deve contenere byte effettivi; fornire un URL come valore non equivale a caricare il file. Lascia che il client imposti il tipo di contenuto multipart e il delimitatore. ^[1]

Salva questo codice come transcribe.py. Scrive un marcatore di invio prima del POST e salva poi l’ID dell’attività accettato. Quando lo esegui di nuovo, legge l’attività esistente. Se l’esito del POST è incerto, il marcatore impedisce allo script di creare un duplicato accidentale.

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

Esegui python transcribe.py. Se stampa processing, attendi qualche secondo e ripeti lo stesso comando. Leggerà l’ID salvato invece di caricare di nuovo. Salva un file di stato separato per ogni registrazione volutamente nuova. Un timeout del client, da solo, non dimostra il fallimento dell’attività.

Leggi la trascrizione completata

La risposta di accettazione contiene id, model, status e created_at. Al completamento vengono aggiunti output.url e output.format. L’URL punta al file risultato; non è un’attività di generazione multimediale che richiede un’altra richiesta a pagamento. Una GET scarica il risultato. ^[1]

Leggi le parole mentre ascolti la registrazione. Controlla nomi, numeri e confini delle frasi prima di usare il testo come sottotitoli o citazione esatta. Una trascrizione è una bozza di ciò che è stato detto e i timestamp non eliminano la necessità di revisionarla.

Le verifiche locali end-to-end del 19 ottobre 2026 hanno completato tutti e cinque i formati di trascrizione e una traduzione con input inglese. Queste verifiche stabiliscono il comportamento di consegna e fatturazione per le registrazioni testate. Non stabiliscono una percentuale di accuratezza o la qualità di traduzione tra lingue.

Scegli testo, timestamp o sottotitoli

Il tuo prossimo passaggio	Scegli	Leggi il file scaricato come
Inserire le parole in un’applicazione	`json`	JSON; inizia da `text`
Modificare una trascrizione semplice	`text`	Testo semplice
Importare sottotitoli in un editor	`srt` o `vtt`	Testo dei sottotitoli
Allineare singole parole o segmenti	`verbose_json`	JSON con i timestamp richiesti

Per i timestamp delle parole, invia response_format=verbose_json e un campo multipart ripetuto chiamato timestamp_granularities[] con valore word. Aggiungi un’altra parte con valore segment se servono entrambi. In Python requests, usa una lista di coppie (name, value) per i campi ripetuti. Ogni timestamp è in secondi. ^[2]

I timestamp delle parole e le etichette dei parlanti sono output diversi. Whisper-1 non trasforma una riunione in una trascrizione con parlanti identificati solo perché richiedi segmenti. Non trasmette neppure testo parziale in streaming: stream viene ignorato per questo modello. Ometti chunking_strategy per il percorso verificato; la selezione esplicita di auto non ha superato la verifica reale di compatibilità. ^[1]

Aggiungi lingua e contesto ortografico quando necessario

Un parametro facoltativo language=en indica alla richiesta di trascrizione che l’input è in inglese. Omettilo per il rilevamento. Se un nome di prodotto può essere frainteso all’ascolto, inserisci la grafia corretta in prompt, nella stessa lingua dell’audio. I prompt Whisper forniscono contesto; non si comportano come istruzioni di chat capaci di imporre in modo affidabile un’impaginazione specifica. ^[3]

Mantieni il contesto pertinente alla clip. Whisper considera solo gli ultimi 224 token del proprio tokenizer. Inviare un documento lungo non fornisce un glossario illimitato alla registrazione, e contare i caratteri non sostituisce in modo affidabile questa regola sui token.

Per la traduzione in inglese, cambia l’endpoint in /audio/translations. I cinque campi di richiesta sono file, model, prompt, response_format e temperature. La traduzione produce inglese; non ha un selettore della lingua di destinazione. Usa un prompt inglese se ne fornisci uno. ^[4]

Controlla i costi prima di ampliare il flusso di lavoro

La tabella dei prezzi attuali qui sotto usa la durata audio misurata. Una trascrizione più lunga non aumenta l’addebito basato sulla durata della stessa registrazione. La durata di ogni file viene arrotondata per eccesso a secondi interi, poi convertita in unità di misurazione audio. Il riferimento API include il calcolo esatto e il Playground mostra una stima quando può leggere la durata della registrazione. Le richieste non riuscite non vengono addebitate.

Model	USD per minute	USD per million audio metering units
whisper-1	$0.036	$36

For each recording: units = round(ceil(duration in seconds) × 1000 / 60). Multiply these audio units by the live unit rate. These are duration units, not transcript tokens. Both transcription and English translation use this rule. Failed requests are not charged.

Prima di elaborare molti file, valida una registrazione rappresentativa e ispeziona il risultato. Conserva l’ID dell’attività per ogni registrazione per recuperare dopo un’interruzione di connessione leggendo lo stato esistente. Consulta il riferimento completo dei parametri prima di aggiungere sottotitoli o combinazioni di formati meno testate.

Domande sulla prima integrazione

Posso usare l’esempio dell’SDK Python OpenAI senza modifiche?

No. I campi di input multipart sono familiari, ma SeedRouter restituisce un ID dell’attività asincrono. Un client sincrono che si aspetta text nella risposta POST deve essere adattato. Questo esempio rende espliciti l’invio e la lettura del risultato.

Perché nel risultato JSON non ci sono i timestamp delle parole?

Il formato predefinito json è una risposta orientata al testo. Richiedi insieme verbose_json e la granularità temporale word. I tempi dei soli segmenti non creano una voce per ogni parola.

Devo inviare un altro POST dopo un timeout?

Controlla prima l’ID dell’attività salvato o la cronologia delle attività. La risposta potrebbe essere andata persa dopo l’accettazione. Leggere un’attività esistente evita di creare un’altra richiesta per la stessa registrazione.

Whisper-1 verrà dismesso?

OpenAI ha annunciato il 26 febbraio 2027 come data di dismissione di Whisper sulla propria API. Questo avviso non stabilisce una data di dismissione per questo servizio. Includi gli avvisi sul ciclo di vita nella lista di manutenzione quando crei una nuova integrazione. ^[5]