Whisper-1 API: Erste Audiotranskription mit Python

Eine erste Whisper-1-API-Anfrage benötigt eine Audiodatei, eine explizite Modell-ID und ein Ausgabeformat. Auf SeedRouter laden Sie die Aufnahme hoch, speichern die zurückgegebene Task-ID und laden das Transkript herunter, sobald dieser Task abgeschlossen ist. Beginnen Sie mit einer kurzen Aufnahme, deren Wortlaut Sie bereits kennen: So bemerken Sie fehlende Wörter und ungewöhnliche Schreibweisen leichter.

Diese Anleitung folgt dem asynchronen Vertrag von SeedRouter. Sie ist kein unverändert übernehmbares synchrones OpenAI-SDK-Beispiel. Die Whisper-1-Modellseite bietet den Playground und den aktuellen Preis; die API-Referenz führt alle Felder und ausstehenden Kompatibilitätsprüfungen auf. ^[1]

Eine Aufnahme vorbereiten

Verwenden Sie Sprachaufnahmen, die Sie verarbeiten dürfen. Eine kurze WAV- oder MP3-Datei eignet sich als Einstieg. Das aktuelle Uploadlimit beträgt 26.214.400 Byte; die Datei muss lesbares Audio mit messbarer Dauer enthalten. Die Endung .mp3 macht eine umbenannte Textdatei nicht zu gültigem Audio. Die Referenz unterscheidet die neun dokumentierten Eingabeformate von denen, die reale Prüfungen bestanden haben. ^[1]

Die folgende Aufnahme ist eigenständige synthetische englische Sprache, die für diese Anleitung erstellt wurde. Ihre Wellenform erscheint auf dem Titelbild. Der dort zitierte Satz stammt aus dem Aufnahmeskript und ist keine Genauigkeitsaussage.

Das 10,31-Sekunden-Beispiel herunterladen. Das Skript lautet: “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.”

Bewahren Sie einen API-Schlüssel in einer serverseitigen Umgebungsvariable auf. Er gehört nicht in eine öffentliche Webseite, ein mobiles Anwendungspaket oder einen geteilten Screenshot. Das folgende Python-Beispiel verwendet requests und liest SEEDROUTER_API_KEY aus der Umgebung.

Die Whisper-1-API-Anfrage einmal senden

Wählen Sie für eine erste Anfrage json. So können Sie anschließend das Feld text der heruntergeladenen Ergebnisdatei lesen, ohne Untertitelzeitcodes zu verarbeiten. Der Multipart-Teil file muss tatsächliche Bytes enthalten; eine URL als Wert ist nicht mit dem Hochladen der Datei gleichzusetzen. Lassen Sie den Client den Multipart-Inhaltstyp und die Grenze festlegen. ^[1]

Speichern Sie dies als transcribe.py. Das Skript schreibt vor dem POST eine Übermittlungsmarkierung und speichert danach die angenommene Task-ID. Beim erneuten Ausführen liest es diesen bestehenden Task. Ist das Ergebnis des POST unklar, verhindert die Markierung, dass das Skript versehentlich ein Duplikat erstellt.

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"])

Führen Sie python transcribe.py aus. Wird processing ausgegeben, warten Sie einige Sekunden und führen denselben Befehl erneut aus. Er liest die gespeicherte ID, statt erneut hochzuladen. Speichern Sie für jede bewusst neue Aufnahme eine separate Statusdatei. Eine Zeitüberschreitung auf Clientseite allein belegt keinen Task-Fehlschlag.

Das fertige Transkript lesen

Die Annahmeantwort enthält id, model, status und created_at. Nach Abschluss kommen output.url und output.format hinzu. Diese URL verweist auf die Ergebnisdatei; es handelt sich nicht um einen Mediengenerierungs-Task, der eine weitere kostenpflichtige Anfrage erfordert. Eine GET-Anfrage lädt die Datei herunter. ^[1]

Lesen Sie den Text, während Sie die Aufnahme anhören. Prüfen Sie Namen, Zahlen und Satzgrenzen, bevor Sie den Text als Untertitel oder wörtliches Zitat verwenden. Ein Transkript ist ein Entwurf des Gesagten; auch Zeitstempel machen die Prüfung nicht überflüssig.

Lokale Ende-zu-Ende-Prüfungen am 19. Oktober 2026 schlossen alle fünf Transkriptionsformate und eine Übersetzung mit englischer Eingabe ab. Diese Prüfungen belegen das Auslieferungs- und Abrechnungsverhalten für die getesteten Aufnahmen. Sie belegen weder eine Genauigkeitsquote noch die sprachübergreifende Übersetzungsqualität.

Text, Zeitstempel oder Untertitel wählen

Ihr nächster Schritt	Wählen Sie	Heruntergeladene Datei lesen als
Wörter in einer Anwendung verwenden	`json`	JSON; beginnen Sie mit `text`
Ein reines Texttranskript bearbeiten	`text`	Reinen Text
Untertitel in einen Editor importieren	`srt` oder `vtt`	Untertiteltext
Einzelne Wörter oder Segmente ausrichten	`verbose_json`	JSON mit angeforderten Zeitstempeln

Senden Sie für Wortzeitstempel response_format=verbose_json und ein wiederholtes Multipart-Feld namens timestamp_granularities[] mit dem Wert word. Ergänzen Sie einen weiteren Teil mit dem Wert segment, wenn Sie beides benötigen. Verwenden Sie in Python requests eine Liste von (name, value)-Paaren für wiederholte Felder. Jeder Zeitstempel ist in Sekunden angegeben. ^[2]

Wortzeitstempel und Sprecherkennzeichnungen sind unterschiedliche Ausgaben. Whisper-1 erstellt aus einer Besprechung nicht allein deshalb ein Transkript mit Sprecherkennzeichnung, weil Sie Segmente anfordern. Es streamt auch keinen Teiltext: stream wird für dieses Modell ignoriert. Lassen Sie chunking_strategy für den geprüften Ablauf weg; die ausdrückliche Auswahl von auto bestand die reale Kompatibilitätsprüfung nicht. ^[1]

Bei Bedarf Sprache und Schreibkontext ergänzen

Ein optionales language=en teilt der Transkriptionsanfrage mit, dass die Eingabe englisch ist. Lassen Sie es zur automatischen Erkennung weg. Wird ein Produktname leicht falsch verstanden, tragen Sie seine korrekte Schreibweise in prompt ein und verwenden dieselbe Sprache wie im Audio. Whisper-Prompts liefern Kontext; sie funktionieren nicht wie Chat-Anweisungen, mit denen sich ein bestimmtes Layout zuverlässig anordnen lässt. ^[3]

Beschränken Sie den Kontext auf das für den Ausschnitt Relevante. Whisper berücksichtigt nur die letzten 224 Token seines eigenen Tokenizers. Ein langes Dokument gibt der Aufnahme kein unbegrenztes Glossar, und das Zählen von Zeichen ist kein verlässlicher Ersatz für diese Token-Regel.

Ändern Sie für eine Übersetzung ins Englische den Endpunkt zu /audio/translations. Seine fünf Anfragefelder sind file, model, prompt, response_format und temperature. Die Übersetzung erzeugt englischen Text; es gibt keine Zielsprachauswahl. Falls Sie einen Prompt angeben, verwenden Sie Englisch. ^[4]

Vor dem Ausbau des Ablaufs die Kosten prüfen

Die folgende aktuelle Tabelle verwendet die gemessene Audiodauer. Ein längeres Transkript erhöht die dauerabhängigen Kosten derselben Aufnahme nicht. Die Dauer jeder Datei wird auf ganze Sekunden aufgerundet und dann in Audio-Abrechnungseinheiten umgerechnet. Die API-Referenz enthält die exakte Berechnung, und der Playground zeigt eine Schätzung an, sobald er die Aufnahmedauer lesen kann. Fehlgeschlagene Anfragen werden nicht berechnet.

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.

Prüfen Sie vor der Verarbeitung vieler Dateien eine repräsentative Aufnahme und sehen Sie sich das Ergebnis an. Bewahren Sie die Task-ID jeder Aufnahme auf, damit Sie nach einem Verbindungsabbruch den bestehenden Status lesen können. Lesen Sie die vollständige Parameterreferenz, bevor Sie Untertitel oder weniger getestete Formatkombinationen ergänzen.

Fragen zur ersten Integration

Kann ich das OpenAI-Python-SDK-Beispiel unverändert verwenden?

Nein. Die Multipart-Eingabefelder sind vertraut, aber SeedRouter gibt eine asynchrone Task-ID zurück. Ein synchroner Client, der text in der POST-Antwort erwartet, muss angepasst werden. Das Beispiel hier zeigt die Übermittlung und das Lesen des Ergebnisses ausdrücklich.

Warum enthält mein JSON-Ergebnis keine Wortzeitstempel?

Das Standardformat json ist eine textorientierte Antwort. Fordern Sie verbose_json zusammen mit der Zeitstempelgranularität word an. Segmentzeitangaben allein erzeugen keinen Eintrag pro Wort.

Soll ich nach einer Zeitüberschreitung erneut einen POST senden?

Prüfen Sie zuerst die gespeicherte Task-ID oder den Task-Verlauf. Die Antwort könnte nach der Annahme verloren gegangen sein. Durch Lesen eines bestehenden Tasks vermeiden Sie eine weitere Anfrage für dieselbe Aufnahme.

Wird Whisper-1 eingestellt?

OpenAI hat den 26. Februar 2027 als Abschalttermin für Whisper in seiner eigenen API angekündigt. Dieser Hinweis legt keinen Abschalttermin für diesen Dienst fest. Nehmen Sie Lebenszyklushinweise beim Aufbau einer neuen Integration in Ihre Wartungscheckliste auf. ^[5]