Der grundlegende Aufruf der Whisper API ist nicht kompliziert: ein POST-Request, eine Audiodatei, ein Key – schon liegt der transkribierte Text vor. Zeit kostet das Detail: Datei über 25 MB, nicht akzeptiertes Format, fehlende Zeitstempel oder eine nach dem Aufteilen verschobene Zeitachse bei langen Audios.

Dieser Artikel geht die Anbindung der Reihe nach durch: Endpoint und Authentifizierung, Format- und Größenlimits, Unterschied zwischen Transkription und Übersetzung, Zeitstempelparameter, Aufrufe mit curl und Python, Aufteilung langer Audios, häufige Fehler und eine Migrationscheckliste.

Hinweis: OpenAI und Whisper sind Marken der jeweiligen Rechteinhaber. Dieser Artikel dient der technischen Anbindung und steht in keiner Verbindung zu OpenAI. Schnittstellenfunktionen, Dateilimits und Abrechnungsregeln können sich ändern; maßgeblich sind die offizielle Dokumentation und die Dokumentation von ZSQH. Preise entnehmen Sie der Preisübersicht. Ob das Gateway die Audioschnittstelle vollständig unterstützt, richtet sich nach der Dokumentation.

1. Zuerst Endpoint und Authentifizierung klären

Audio- und Chat-Schnittstelle liegen auf unterschiedlichen Pfaden. Transkription nutzt /v1/audio/transcriptions, Übersetzung /v1/audio/translations. Beide sind POST-Anfragen mit multipart/form-data, nicht JSON. Die Authentifizierung folgt dem OpenAI-Stil mit Bearer Token.

Punkt Erläuterung
Transkriptions-Endpoint POST /v1/audio/transcriptions
Übersetzungs-Endpoint POST /v1/audio/translations
Auth-Header Authorization: Bearer <API_KEY>
Request-Typ multipart/form-data
Offizielle Base URL https://api.openai.com/v1
Gateway-Base-URL https://ai.zhongshangqihang.com/v1; Unterstützung der Audioschnittstelle laut Dokumentation

Der Key gehört ausschließlich auf den Server. Ein Key in Browser, App oder öffentlichem Repository ist gleichbedeutend mit der Übergabe des Kontos. Gateways unterscheiden sich im Weiterleitungsumpfang für Audioschnittstellen; prüfen Sie vor der Anbindung in der Preisübersicht oder der Dokumentation, ob das Modell verfügbar ist.

2. Unterstützte Formate und die 25-MB-Grenze

Offiziell genannt werden die Eingabeformate mp3, mp4, mpeg, mpga, m4a, wav und webm bei maximal 25 MB pro Datei. Bei flac, ogg und ähnlichen Formaten nicht auf gut Glück setzen, sondern vor dem Upload transcodieren.

25 MB ist eine Dateigrenze, keine Dauerbegrenzung. Je höher die Bitrate, desto kürzer die Dauer, die hineinpasst: Eine 16-kHz-Mono-MP3 kann sehr lange sein, eine 48-kHz-Stereo-WAV überschreitet das Limit möglicherweise nach gut zehn Minuten. Vor dem Upload einheitlich auf 16 kHz, Mono und mp3 oder wav zu konvertieren, ist die sicherste Vorverarbeitung.

3. Transkription und Übersetzung sind nicht dasselbe

/audio/transcriptions wandelt Audio in Text der Originalsprache um; ein deutsches Audio ergibt deutschen Text. /audio/translations übersetzt Audio ins Englische; die offizielle Dokumentation nennt ausdrücklich nur Englisch als Ziel und verwendet whisper-1. Für deutsche Untertitel die Transkription verwenden und nicht auf die Übersetzungsschnittstelle setzen.

Der Sprachparameter verwendet ISO-639-1-Codes, etwa de, en oder ja. Ohne Angabe erkennt das Modell die Sprache automatisch, was bei kurzen Audios, gemischtsprachigen Inhalten oder starkem Akzent leicht fehlgeht. Bei klarer Geschäftssprache ist die explizite Angabe stabiler.

4. Minimalbeispiel mit curl

curl "https://ai.zhongshangqihang.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "language=de" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=segment"

Drei Punkte beachten: Das Dateifeld verwendet -F; timestamp_granularities[] braucht die eckigen Klammern; nur verbose_json liefert die Segmentstruktur. Unterstützt das Gateway einen Parameter nicht, ihn zuerst entfernen und erneut testen, um die Ursache schrittweise einzugrenzen.

5. Python-Aufruf und Zeitstempel

import os
from openai import OpenAI

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

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

for seg in result.segments:
    print(f"{seg.start:.1f}-{seg.end:.1f}  {seg.text}")

Zeitstempel gibt es auf zwei Ebenen: segment ist satz- bzw. abschnittsweise und eignet sich für Untertitel und Besprechungsnotizen; word ist wortgenau und eignet sich für zeichengenaue Ausrichtung. Laut offizieller Dokumentation wirkt timestamp_granularities[] derzeit nur bei whisper-1 und erfordert verbose_json. Neuere Transkriptionsmodelle können bei der Genauigkeit besser sein, unterscheiden sich aber in der Unterstützung von Zeitstempeln und Untertitelformaten; vor der Auswahl die Dokumentation prüfen.

Bei vielen Eigennamen lassen sich Personen-, Produkt- und Fachbegriffe über prompt übergeben. Die offizielle Dokumentation nennt für whisper-1 eine Prompt-Obergrenze von 224 Token; darüber kann gekürzt werden, daher nur die wichtigsten Begriffe aufnehmen.

Wenn nur Text benötigt wird, response_format auf json oder text setzen; für Untertiteldateien direkt srt oder vtt anfordern. Mehr Formate bedeuten größere Antworten; bei Batch-Szenarien Bandbreite und Parsing-Aufwand abwägen.

6. Lange Audios zuerst aufteilen, dann transkribieren

Audios über 25 MB müssen geteilt werden. Empfohlener Ablauf:

  1. Mit ffmpeg einheitlich auf 16 kHz Mono konvertieren, um das Volumen zu reduzieren.
  2. Nach Stilleerkennung oder festen 10-Minuten-Abschnitten teilen und nicht mitten im Satz schneiden.
  3. Den Startoffset jedes Abschnitts festhalten, etwa part_000 bei 0 Sekunden und part_001 bei 600 Sekunden.
  4. Abschnittsweise die Transkriptionsschnittstelle aufrufen und die Rohantwort speichern.
  5. Beim Zusammenführen den Offset zu den Zeitstempeln jedes Abschnitts addieren.
  6. Rund um die Schnittstellen stichprobenartig prüfen und doppelte Wörter sowie Auslassungen korrigieren.

Zwischen den Abschnitten können 0,5 bis 1 Sekunde Überlappung liegen, um Wortverluste an den Grenzen zu reduzieren. Die Überlappung wird jedoch doppelt transkribiert und muss beim Zusammenführen dedupliziert werden. Das Aufteilungsskript sollte die Offset-Liste mitspeichern; raten Sie die Zeit nicht aus Dateinamen. Nicht übereinstimmende Dateinamen, Reihenfolge und Offsets sind die häufigste Ursache für Fehler beim Zusammenführen. Parallelität verkürzt die Gesamtdauer, darf aber die Ratenlimits des Kontos nicht überschreiten; sonst bremsen 429-Wiederholungen den Fortschritt.

7. Häufige Fehler eingrenzen

  • 401: falscher oder abgelaufener Key oder fehlendes Bearer.
  • 404: falsche Base URL oder falscher Pfad; prüfen, ob /v1/audio/transcriptions verwendet wird.
  • 400: nicht unterstütztes Format, falsch geschriebener Parameter oder ein Parameter, den das Modell nicht unterstützt.
  • 413: Datei über dem Größenlimit; komprimieren oder aufteilen.
  • 429: Parallelität oder Kontingent überschritten; Parallelität senken und mit exponentiellem Backoff wiederholen.
  • 5xx oder Timeout: Server- oder Netzproblem; Wiederholungen begrenzen, um doppelte Abrechnung zu vermeiden.
  • Leerer Text: Audio stumm, zu leise oder Sprache falsch erkannt; zuerst die Datei prüfen und language angeben.
  • Keine Zeitstempel: response_format ist nicht verbose_json, oder das Modell ist nicht whisper-1.

8. Migrationscheckliste vom offiziellen Dienst zum Gateway

  1. Base URL und Pfad der Audioschnittstelle des Ziel-Gateways bestätigen.
  2. Prüfen, ob das benötigte Modell verfügbar ist und der Name mit dem offiziellen übereinstimmt.
  3. JSON-Request-Body auf multipart/form-data umstellen.
  4. response_format angleichen und prüfen, ob der Code vom Feld segments abhängt.
  5. Testen, ob die Zeitstempelparameter unterstützt werden; andernfalls auf Abschnittsebene oder lokale Ausrichtung zurückfallen.
  6. Sinnvolle Timeouts und maximale Wiederholungszahlen setzen.
  7. Im Log keine vollständigen Audioadressen und Keys festhalten; Textergebnisse wie sensible Daten behandeln.
  8. Mit einer Gruppe echter Geschäftsaufnahmen regressieren und Wortfehlerrate sowie Zeitachse vergleichen.
  9. Einen Rückfallweg vorbereiten: Modellwechsel, Regionswechsel oder Rückkehr zur offiziellen Schnittstelle.

Häufige Fragen

Worin unterscheidet sich die Whisper API vom Open-Source-Modell Whisper?

Das Open-Source-Modell lässt sich selbst betreiben, die Daten bleiben lokal, aber Grafikkarte, Betrieb und Optimierung gehen zu Ihren Lasten. Die gehostete API erspart das Deployment, rechnet nach Nutzung ab und eignet sich für schnellen Start und schwankenden Traffic.

Ist 25 MB eine Begrenzung der Audiodauer?

Nein, eine Dateigrößenbegrenzung. Eine niedrigere Bitrate und Mono verlängern die mögliche Dauer deutlich; über dem Limit muss aufgeteilt werden.

Warum fehlen wortgenaue Zeitstempel?

Wortgenaue Zeitstempel erfordern gleichzeitig whisper-1, verbose_json und timestamp_granularities=["word"]. Ein anderes Modell oder Format kann dazu führen, dass das Feld fehlt.

Kann die Übersetzungsschnittstelle Englisch nach Deutsch übersetzen?

Nein. Die offizielle Übersetzungsschnittstelle liefert nur Englisch. Für deutsche Inhalte die Transkription verwenden und anschließend ein Textmodell zur Übersetzung einsetzen.

Lässt sich die offizielle Base URL direkt durch das Gateway ersetzen?

Bei Textschnittstellen meist ja; bei Audioschnittstellen müssen Pfad und Parameter vom Gateway weitergeleitet werden. Vor der Anbindung mit einem kurzen Audio eine vollständige Prüfung durchführen und nicht von Kompatibilität ausgehen.

Nächster Schritt

Registrieren Sie sich beim ZSQH AI Gateway, legen Sie einen Test-Key an und transkribieren Sie zunächst ein einminütiges Audio. Danach Zeitstempel und die Aufteilung langer Audios prüfen. Modelle und Preise stehen in der Preisübersicht.

Weiterlesen: