Wenn die Audiotranskription fehlschlägt, wird oft zuerst das Modell gewechselt oder die Erkennungsleistung infrage gestellt. Die meisten Störungen entstehen jedoch auf vier Ebenen: Datei, Authentifizierung, Netzwerk und Rate-Limit. Die Transkriptionsschnittstelle ist ein multipart/form-data-Upload und damit komplexer als eine reine Text-API; die Prüfreihenfolge sollte entsprechend länger sein. Zuerst HTTP-Status und Fehlertyp, dann die Anfrage selbst, erst zuletzt Audio und Prompt anpassen.

Dieser Artikel behandelt 401, 400-Formatfehler, 413 bei zu großen Dateien, 429-Rate-Limits, Timeouts sowie leere oder unlesbare Transkripte. Dazu gibt es Prüfpfade und wiederverwendbaren Code. Dateigrenzen, Modellnamen und Fehlerformate können sich mit der Version ändern; maßgeblich sind die offizielle Dokumentation und die Plattformdokumentation. Preise stehen unter Modellpreise.

Hinweis: OpenAI und Whisper sind Marken der jeweiligen Rechteinhaber. Dieser Artikel dient ausschließlich der technischen Integrationshilfe. Schnittstellengrenzen, unterstützte Formate und Modellnamen können sich ändern; maßgeblich sind die offizielle Dokumentation und die Dokumentation der Plattform.

1. Zuerst eine Prüfreihenfolge festlegen

Symptom Häufiger Status Häufige Ursache Richtung
Authentifizierung fehlgeschlagen 401, 403 Falscher Key, fehlendes Bearer, keine Audiorechte Zugangsdaten korrigieren, nicht wiederholen
Format nicht unterstützt 400 Codec nicht in der Liste, Endung passt nicht zum Inhalt Transkodieren und erneut senden
Datei zu groß 413 oder 400 Obergrenze für einzelne Dateien überschritten Komprimieren oder teilen
Zu viele Anfragen 429 Anfragen pro Minute, Parallelität oder Kontingent überschritten Backoff, Queue, Keys trennen
Serverfehler 500, 502, 503 Upstream gestört oder überlastet Backoff, begrenzt wiederholen
Timeout Keine Antwort oder Verbindungsabbruch Große Datei, langsamer Upload, lange Verarbeitung Teilen, Timeouts anpassen
Leerer Text 200 Stille, niedrige Lautstärke, falsche Sprache, Codec-Problem Audio prüfen statt wiederholen

Falls Antwortheader oder Fehlerkörper eine request-id enthalten, unbedingt behalten. Bei der Fehlersuche beim Anbieter helfen eine Request-ID und ein minimales reproduzierbares Audio mehr als zehn Screenshots.

2. 401: zuerst Header, dann Key prüfen

401 bedeutet, dass die Authentifizierung nicht durchgelassen wurde, meist unabhängig von Guthaben oder Modellfähigkeit. Prüfreihenfolge:

  1. Ist der Header Authorization: Bearer <key> korrekt, einschließlich Bearer und Leerzeichen?
  2. Enthält der Key Leerzeichen, Zeilenumbrüche oder Anführungszeichen am Anfang oder Ende? Beim Kopieren aus Chatfenstern passiert das leicht.
  3. Wurde die Umgebungsvariable tatsächlich geladen? Nur ein Präfix ausgeben, niemals den vollständigen Key protokollieren.
  4. Wurde der Key widerrufen, gehört er zum richtigen Projekt, hat das Konto Audiorechte?
  5. Stimmen Basis-URL https://ai.zhongshangqihang.com/v1 und Pfad /v1/audio/transcriptions?
  6. Bei einem Gateway prüfen, ob der Audiozugang freigeschaltet ist. Aus „Text funktioniert“ folgt nicht automatisch „Audio funktioniert“.

Ein weiterer häufiger Fehler: die Datei in einen JSON-Body legen. Die Transkriptionsschnittstelle verlangt multipart/form-data; auf der Kommandozeile also curl -F "file=@meeting.mp3" statt -d. Ein falscher Body erscheint manchmal als 400, kann aber auch als 401 zurückkommen, wenn keine gültigen Zugangsdaten gelesen werden.

3. 400 und 413: Format und Größe

Bei 400 ist das häufigste Problem ein nicht unterstütztes Format. Die offizielle Dokumentation nennt unter anderem mp3, mp4, mpeg, mpga, m4a, wav und webm; vollständige Liste und Codec-Anforderungen richten sich nach der aktuellen Dokumentation. Eine Endung umzubenennen ist keine Transkodierung: Wird .amr in .mp3 umbenannt, liest der Server weiterhin den ursprünglichen Codec und meldet erneut einen Fehler.

413 bedeutet meist, dass die Datei die Obergrenze überschreitet; die offizielle Grenze liegt häufig bei 25 MB, maßgeblich ist die Dokumentation. Zwei Wege:

  • Komprimieren: einheitlich 16 kHz mono; für Sprache ist keine hohe Bitrate nötig. Beispiel: ffmpeg -i input.mp3 -ac 1 -ar 16000 -b:a 64k output.mp3.
  • Teilen: in 10-Minuten-Abschnitte schneiden, einzeln transkribieren und zusammenführen. Schnittpunkte nach Möglichkeit in Stille legen und einen kleinen Überlapp lassen, damit keine Wörter zerteilt werden.

Langes Audio nicht nur durch Kompression durchzudrücken versuchen. Je größer die Datei, desto langsamer der Upload, desto wahrscheinlicher ein Timeout und desto teurer ein erneuter Versuch. Paralleles Teilen ist stabiler, aber die Parallelität muss begrenzt werden, sonst wird aus 413 ein 429.

4. 429: Rate-Limit ist nicht gleich fehlendes Guthaben

429 zeigt, dass Rate, Parallelität oder Kontingent überschritten wurden. Trotz gleichem Status kann der Fehlertyp unterschiedlich sein: Mal ist die Frequenz zu hoch, mal das Guthaben zu niedrig. Erst den Typ lesen, dann entscheiden, ob Warten, Senken der Parallelität oder Aufladen hilft.

Typische Auslöser: zu viele parallele Batch-Aufgaben; mehrere Dienste teilen einen Key; sofortige Wiederholung nach einem Fehler erzeugt eine Retry-Flut; langes Audio belegt Verbindungen zu lange; Gratis- oder niedrige Tarife haben kleine Minutenkontingente.

Vorgehen: zuerst prüfen, ob Retry-After vorhanden ist, dann exponentielles Backoff mit Jitter; Batch-Aufgaben in eine Queue legen und gleichzeitig laufende Anfragen begrenzen; Keys nach Projekt trennen; Obergrenzen und Warnungen für Wiederholungen setzen, keine Endlosschleife. Transkription wird nach Audiodauer abgerechnet; wiederholte Übermittlung kann doppelt kosten. Vor einer Wiederholung prüfen, ob der vorherige Versuch bereits erfolgreich war.

5. Timeouts: langsamer Upload oder langsame Verarbeitung?

Ein Timeout kann in drei Phasen auftreten: Verbindungsaufbau, Upload, serverseitige Verarbeitung. Wenn schon kleine Dateien timeouten, zuerst Netzwerk, Proxy und Basis-URL prüfen; wenn große Dateien regelmäßig timeouten, zuerst teilen und komprimieren.

Der Client sollte Timeouts explizit setzen und nicht auf Standardwerte vertrauen. Die Dauer hängt von Audiolänge, Dateigröße und Warteschlange ab. Eine großzügige, aber begrenzte Obergrenze von beispielsweise zwei bis drei Minuten setzen und über Aufgabenprotokolle unterscheiden, ob eine Anfrage „übermittelt, aber nicht zurückgekehrt“ oder „nie gesendet“ wurde. Automatische Wiederholung nach Timeout ist heikel: Hat der Server bereits verarbeitet, entstehen zweite Kosten und doppelte Ergebnisse.

6. 200, aber leerer Text oder Zeichensalat

Diese Fälle haben keinen HTTP-Fehler, die Ursachen liegen woanders.

Leerer Text tritt auf bei: durchgehender Stille oder zu niedriger Lautstärke; falschem Sprachparameter; anomalem Kanal, bei dem die Hauptspur stumm ist; einer Datei, die sich hochladen, aber nicht dekodieren lässt. Zuerst Lautstärke prüfen, explizit language=de senden und dann einheitlich auf 16 kHz mono umwandeln.

Zeichensalat oder viele falsche Wörter entstehen durch falsch erkannte Sprache, starken Dialekt, Musik im Hintergrund, gleichzeitiges Sprechen oder zu großen Aufnahmeabstand. Im Request können über prompt Namen, Produktbezeichnungen und Fachbegriffe mitgegeben und anschließend per Wörterbuch ersetzt werden. Ist das Audio selbst unbrauchbar, rettet auch ein anderes Modell nichts; dann zurück zu Aufnahme und Vorverarbeitung.

7. Wiederholungen und Segmentierung: wiederverwendbarer Code

Wiederholungen sind nur bei temporären Fehlern sinnvoll. Bei 401, 400 und 413 muss die Anfrage geändert werden; blindes Wiederholen verschärft das Problem.

import os
import random
import time
from openai import (
    OpenAI,
    APIConnectionError,
    APIStatusError,
    APITimeoutError,
    RateLimitError,
)

client = OpenAI(
    api_key=os.environ["WHISPER_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
    timeout=180,
)

def transcribe(path: str, model: str = "whisper-1", retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            with open(path, "rb") as f:
                result = client.audio.transcriptions.create(
                    model=model,
                    file=f,
                    language="de",
                    response_format="verbose_json",
                )
            text = (result.text or "").strip()
            if not text:
                raise ValueError("Leeres Transkript: Lautstärke, Sprache und Kanal prüfen")
            return text
        except RateLimitError:
            wait = min(2 ** attempt, 30) + random.random()
            print(f"429, neuer Versuch in {wait:.1f}s")
            time.sleep(wait)
        except (APITimeoutError, APIConnectionError):
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIStatusError as exc:
            if exc.status_code >= 500:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise  # 400/401/413: Anfrage ändern, nicht wiederholen
    raise RuntimeError("Maximale Anzahl Wiederholungen erreicht")

print(transcribe("meeting.mp3"))

Modellnamen richten sich nach der Plattformdokumentation; whisper-1 ist nur ein übliches Beispiel. Audio über der Größengrenze zuerst mit ffmpeg teilen und die Funktion auf jedes Segment anwenden; beim Zusammenführen die Startzeit jedes Segments wieder addieren.

8. Logging und Checkliste für die Fehlersuche beim Anbieter

  1. Zeitpunkt, Zeitzone, HTTP-Status und Fehlertyp erfassen.
  2. request-id notieren und festhalten, ob der offizielle Zugang oder ein Gateway aufgerufen wurde.
  3. Dateiname, tatsächlicher Codec, Dauer, Größe, Samplerate und Kanalzahl erfassen.
  4. Zentrale Parameter wie model, language und response_format protokollieren.
  5. Anzahl der Wiederholungen, jeweilige Wartezeit und Endergebnis festhalten.
  6. Vermerken, ob ein geteilter Key verwendet wurde, sowie Parallelität und Batch-Größe zum Zeitpunkt des Fehlers.
  7. Ein 10 bis 30 Sekunden langes, freigebbares Minimalaudio ohne personenbezogene Daten vorbereiten.

Beim Anbieter niemals den vollständigen Key und ohne Einwilligung keine Kundenaufnahmen einreichen. Ein stabil reproduzierbares Minimalbeispiel hilft weit mehr als die Beschreibung „manchmal kommt ein Fehler“.

Häufige Fragen

413 und 400 betreffen beide die Datei – wo liegt der Unterschied?

413 bedeutet meist, dass die Größe die Obergrenze überschreitet; Lösung sind Kompression oder Teilung. 400 betrifft eher Format, Parameter oder Codec; Lösung sind Transkodierung und Feldprüfung. Fehlertyp und Meldung lesen, nicht nur den Statuscode.

Was tun, wenn 429 nicht verschwindet?

Zuerst unterscheiden, ob die Frequenz oder das Guthaben der Grund ist. Bei Frequenz Parallelität senken, in eine Queue legen und Keys trennen; bei Guthaben aufladen oder den Zugang wechseln. Bei anhaltendem 429 nicht weiter verdichten, sonst dauert die Erholung länger.

Sollte nach einem Timeout sofort wiederholt werden?

Erst prüfen, ob die Anfrage serverseitig bereits abgeschlossen wurde. Die Transkription kann bereits abgerechnet sein; eine direkte Wiederholung erzeugt doppelte Ergebnisse und Kosten. Über Aufgabenprotokoll oder Idempotenz den Status klären und dann entscheiden.

Ist ein leeres Transkript ein Modellfehler?

Meist nicht. Zuerst Lautstärke, Stilleabschnitte, Sprachparameter, Kanal und tatsächlichen Codec prüfen. Dasselbe Audio über einen anderen Zugang testen, trennt Audio- von Dienstproblemen schnell.

Wie unterscheidet man Gateway-Fehler von offiziellen Fehlern?

request-id und Fehlertyp behalten und dieselbe Anfrage über beide Zugänge senden. Funktioniert der offizielle Zugang und scheitert das Gateway, liegt es meist an Gateway-Konfiguration oder Weiterleitung. Scheitern beide, Key, Netzwerk und Audiodatei prüfen.

Nächste Schritte

Zunächst bei ZSQH AI Gateway registrieren und mit einer einminütigen Audiodatei 401, 413, 429 und Timeout je einmal durchspielen, bevor die Produktionsüberwachung angebunden wird. Verfügbarkeit der Modelle und Preise stehen unter Modellpreise.

Weiterlesen: