OpenAI Whisper Patterns
Kurzanleitung: Verwenden Sie
client.audio.transcriptions.create()für Sprache-zu-Text undclient.audio.translations.create()für nicht-englische Audioinhalte in englischen Text. Wählen Siegpt-4o-transcribefür höchste Genauigkeit,gpt-4o-mini-transcribefür Kosteneffizienz,whisper-1für Zeitstempel/SRT/VTT odergpt-4o-transcribe-diarizezur Sprecheridentifikation. Dateien müssen kleiner als 25 MB sein – chunkieren Sie größere Dateien. Verwenden Sieprompt, um Wortschatz und Stil zu steuern. Streaming ist überstream: truefür progressive Ausgabe beigpt-4o-transcribe-Modellen verfügbar.
<critical_requirements>
KRITISCH: Vor Verwendung dieser Fähigkeit
Der gesamte Code muss den Projektkonventionen in CLAUDE.md folgen (Kebab-Case, benannte Exporte, Import-Reihenfolge,
import type, benannte Konstanten)
(Sie MÜSSEN das richtige Modell für den Anwendungsfall wählen – gpt-4o-transcribe für Genauigkeit, whisper-1 für Zeitstempel/SRT/VTT-Ausgabe, gpt-4o-transcribe-diarize für Sprecherbezeichnungen)
(Sie MÜSSEN Audiodateien größer als 25 MB vor dem Senden an die API chunkieren – die API lehnt Dateien ab, die dieses Limit überschreiten)
(Sie MÜSSEN response_format: "verbose_json" übergeben, wenn Sie timestamp_granularities verwenden – Zeitstempel funktionieren nur mit diesem Format bei whisper-1)
(Sie MÜSSEN chunking_strategy: "auto" setzen, wenn Sie gpt-4o-transcribe-diarize mit Audio länger als 30 Sekunden verwenden – die API erfordert es)
</critical_requirements>
Auto-Erkennung: Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, speech-to-text, diarization, diarized_json, timestamp_granularities, verbose_json
Wann zu verwenden:
- Transkribieren von Audiodateien (Besprechungen, Interviews, Podcasts, Sprachnotizen) in Text
- Übersetzen von nicht-englischen Audioinhalten in englischen Text
- Generieren von Untertiteln im SRT- oder VTT-Format aus Audio
- Abrufen von Zeitstempeln auf Wort- oder Segmentebene für die Videobearbeitung
- Identifizieren von Sprechern in Audioinhalten mit mehreren Sprechern (Diarisierung)
- Streamen von Transkriptionsergebnissen progressiv, während das Modell Audio verarbeitet
Wichtigste abgedeckte Muster:
- Modellauswahl (whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
- Antwortformate (json, text, srt, vtt, verbose_json, diarized_json)
- Zeitstempel (Wortebene, Segmentebene) und Untertitelgenerierung
- Prompting für Wortschatz, Akronyme und Stil
- Chunking großer Dateien (> 25 MB) mit Kontexterhaltung
- Streaming-Transkription mit
stream: true - Übersetzung ins Englische über
audio.translations.create() - Sprecher-Diarisierung mit Sprecherreferenzen
Wann NICHT zu verwenden:
- Text-zu-Sprache (TTS) – verwenden Sie die OpenAI TTS API (
client.audio.speech.create()) - Echtzeit-bidirektionale Sprachgespräche – verwenden Sie die OpenAI Realtime API
- Transkription mit Nicht-OpenAI-Anbietern – verwenden Sie ein anbieterunabhängiges Sprach-SDK
Beispiele-Index
- Kern: Transkription, Übersetzung, Zeitstempel, Chunking, Streaming, Diarisierung – Alle Audio-API-Muster
Philosophie
Die OpenAI Audio API bietet Sprache-zu-Text-Transkription und -Übersetzung über mehrere Modelle, die für unterschiedliche Anforderungen optimiert sind. Die API ist einfach – Sie senden eine Audiodatei und erhalten Text zurück – aber die Wahl des richtigen Modells, Antwortformats und der Parameter ist entscheidend für qualitativ hochwertige Ergebnisse.
Kernprinzipien:
- Modellauswahl ist wichtig –
gpt-4o-transcribeliefert die höchste Genauigkeit mit niedrigeren Halluzinationsraten.whisper-1ist das einzige Modell, das SRT/VTT/verbose_json mit Zeitstempeln unterstützt.gpt-4o-transcribe-diarizefügt die Sprecheridentifikation hinzu. - Dateigröße ist die primäre Einschränkung – 25 MB-Limit bedeutet, dass Sie längeres Audio chunkieren müssen. Trennen Sie an Satzgrenzen, um den Kontext zu erhalten.
- Prompting verbessert die Genauigkeit – Der
prompt-Parameter steuert Wortschatz, Akronyme und Formatierungsstil. Er gibt keine Anweisungen – er liefert Kontext, mit dem das Modell abgleicht. - Das Antwortformat bestimmt die verfügbaren Funktionen – Zeitstempel erfordern
verbose_jsonbeiwhisper-1. Diarisierung erfordertdiarized_json. SRT/VTT sind nur beiwhisper-1verfügbar.
Wann die Audio-API verwendet werden sollte:
- Sie benötigen eine genaue Transkription von aufgenommenen Audiodateien
- Sie benötigen Untertitel (SRT/VTT) aus Audio
- Sie müssen identifizieren, wer in einem Gespräch spricht
- Sie müssen nicht-englische Sprache in englischen Text übersetzen
Wann NICHT zu verwenden:
- Echtzeit-Sprachchat – verwenden Sie stattdessen die Realtime API
- Text-zu-Sprache – verwenden Sie
client.audio.speech.create() - Sie benötigen eine Transkription in einer nicht-englischen Zielsprache (Übersetzung gibt nur Englisch aus)
Kernmuster
Muster 1: Einfache Transkription
Senden Sie eine Audiodatei und erhalten Sie Text zurück. Das Modell erkennt die Sprache automatisch.
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
});
Verwenden Sie gpt-4o-transcribe für höchste Genauigkeit. Verwenden Sie NICHT whisper-1 mit verbose_json, wenn Sie nur Klartext benötigen – es erhöht den Overhead und hat höhere Halluzinationsraten. Vollständige Beispiele finden Sie in core.md.
Muster 2: Modellauswahl
Jedes Modell hat unterschiedliche Fähigkeiten und Kompromisse.
Was brauchen Sie?
+-- Höchste Genauigkeit, Klartext -> gpt-4o-transcribe
+-- Kosteneffizient, Klartext -> gpt-4o-mini-transcribe
+-- Zeitstempel (Wort/Segment) -> whisper-1 (verbose_json)
+-- SRT- oder VTT-Untertitel -> whisper-1 (srt/vtt-Format)
+-- Sprecheridentifikation -> gpt-4o-transcribe-diarize
+-- Streaming-Ausgabe -> gpt-4o-transcribe oder gpt-4o-mini-transcribe
Modellfähigkeiten-Matrix
| Funktion | whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| Antwortformate | json, text, srt, vtt, verbose_json | json, text | json, text | json, text, diarized_json |
| Zeitstempel | Wort + Segment | Nein | Nein | Nein |
| Streaming | Nein | Ja | Ja | Nein |
| Prompt-Unterstützung | Ja (224 Token) | Ja | Ja | Nein |
| Logprobs | Nein | Ja | Ja | Nein |
| Sprecherbezeichnung | Nein | Nein | Nein | Ja |
| Sprachparameter | Ja | Ja | Ja | Ja |
Muster 3: Prompting für Wortschatz und Stil
Der prompt-Parameter liefert Kontext – keine Anweisungen. Er steuert die Schreibweise von Namen, Akronymen und den Formatierungsstil. Verwenden Sie ihn nicht, um Anweisungen wie „bitte sorgfältig transkribieren“ zu geben – er gleicht Stil- und Vokabular-Kontext ab.
const VOCABULARY_PROMPT = "Kubernetes, kubectl, etcd, NGINX, gRPC, PostgreSQL";
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
prompt: VOCABULARY_PROMPT,
});
Anwendungsfälle: Akronyme/Eigennamen, Kontexterhaltung über Chunks hinweg (vorherigen Transkriptionsanhängsel übergeben), Beibehalten von Füllwörtern, Schreibstil-Vorgaben. Detaillierte Vokabelbeispiele finden Sie in core.md.
Muster 4: Chunking großer Dateien
Audiodateien, die 25 MB überschreiten, müssen vor der Transkription aufgeteilt werden. Trennen Sie an Satzgrenzen (z. B. via ffmpeg), um den Kontext zu erhalten. Übergeben Sie den Anhängsel des vorherigen Transkripts als prompt für die Kontinuität über Chunks hinweg.
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// Mit ffmpeg teilen: ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Dann nacheinander transkribieren, vorherigen Kontext via prompt übergeben
Die vollständige Chunking-Implementierung mit Größenvalidierung und Kontexterhaltung finden Sie in core.md.
Muster 5: Streaming-Transkription
Streamen Sie partielle Transkriptionsergebnisse, während das Modell Audio verarbeitet. Nur gpt-4o-transcribe und gpt-4o-mini-transcribe unterstützen stream: true. Hören Sie auf transcript.text.delta-Ereignisse für progressive Ausgabe und transcript.text.done für den Abschluss. Verwenden Sie NICHT stream: true mit whisper-1 – es wird nicht unterstützt.
const stream = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
stream: true,
});
for await (const event of stream) {
if (event.type === "transcript.text.delta") process.stdout.write(event.delta);
}
Vollständige Streaming- und Logprob-Beispiele finden Sie in core.md.
Muster 6: Übersetzung ins Englische
Übersetzen Sie nicht-englische Audioinhalte in englischen Text. Nur whisper-1 wird über audio.translations.create() unterstützt. Für gleichsprachige Transkription verwenden Sie stattdessen audio.transcriptions.create(). Die Übersetzung gibt nur Englisch aus – es gibt keine Möglichkeit, in andere Sprachen zu übersetzen.
const translation = await client.audio.translations.create({
model: "whisper-1",
file: createReadStream(audioPath),
});
Vollständige Übersetzungsbeispiele inklusive Vokabel-Prompting finden Sie in core.md.
Muster 7: Sprecher-Diarisierung
Identifizieren Sie, wer in Audio mit mehreren Sprechern spricht. Verwenden Sie gpt-4o-transcribe-diarize mit response_format: "diarized_json" und chunking_strategy: "auto" (erforderlich für Audio > 30s). Diarisierung unterstützt kein prompt, logprobs oder timestamp_granularities.
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe-diarize",
file: createReadStream(audioPath),
response_format: "diarized_json",
chunking_strategy: "auto",
});
Optional können Sie known_speaker_names und known_speaker_references (2-10 Sekunden Audioclips als Data-URLs) angeben, um Segmente bekannten Sprechern zuzuordnen (bis zu 4). Vollständige Diarisierungsbeispiele finden Sie in core.md.
<decision_framework>
Entscheidungsrahmen
Welches Modell wählen
Was brauchen Sie von der Transkription?
+-- Nur Text (höchste Genauigkeit) -> gpt-4o-transcribe
+-- Nur Text (kostensensitiv) -> gpt-4o-mini-transcribe
+-- Wort-/Segment-Zeitstempel -> whisper-1 (verbose_json)
+-- SRT- oder VTT-Untertiteldateien -> whisper-1 (srt oder vtt)
+-- Sprecheridentifikation -> gpt-4o-transcribe-diarize
+-- Progressive/Streaming-Ausgabe -> gpt-4o-transcribe (stream: true)
Welches Antwortformat verwenden
Welche Ausgabe benötigen Sie?
+-- Klartext-String -> "text"
+-- JSON mit Textfeld -> "json" (Standard)
+-- Untertitel für Video -> "srt" oder "vtt" (nur whisper-1)
+-- Zeitstempel (Wort/Segment) -> "verbose_json" (nur whisper-1)
+-- Sprecher-gekennzeichnete Segmente -> "diarized_json" (nur gpt-4o-transcribe-diarize)
Transkription vs. Übersetzung
Ist das Audio auf Englisch?
+-- JA -> Verwenden Sie audio.transcriptions.create()
+-- NEIN -> Möchten Sie die Ausgabe in der Originalsprache?
+-- JA -> Verwenden Sie audio.transcriptions.create() (erkennt Sprache automatisch)
+-- NEIN (möchten Englisch) -> Verwenden Sie audio.translations.create() (nur whisper-1)
</decision_framework>
<red_flags>
ROTE FLAGGEN
Probleme mit hoher Priorität:
- Verwendung von
timestamp_granularitiesohneresponse_format: "verbose_json"beiwhisper-1(wird stillschweigend ignoriert) - Senden von Dateien größer als 25 MB (API gibt Fehler zurück)
- Verwendung von
gpt-4o-transcribe-diarizeohnechunking_strategybei Audio > 30 Sekunden (API gibt Fehler zurück) - Verwendung von
stream: truemitwhisper-1(nicht unterstützt)
Probleme mit mittlerer Priorität:
- Verwendung von
whisper-1, wenngpt-4o-transcribeeine höhere Genauigkeit liefern würde (whisper-1 hat höhere Halluzinationsraten) - Nichtübergeben des
language-Parameters, wenn Sie die Sprache kennen (Auto-Erkennung kann bei kurzem oder verrauschtem Audio falsch sein) - Verwendung von
audio.translations.create(), wenn Sie eine gleichsprachige Transkription wünschen (Übersetzung gibt immer Englisch aus) - Aufteilen von Audio mitten im Satz beim Chunking (verliert Kontext an den Grenzen)
Häufige Fehler:
- Den
prompt-Parameter als Anweisung behandeln („bitte sorgfältig transkribieren“) – er ist Kontext für Vokabel- und Stilabgleich - Verwendung von
gpt-4o-transcribe, wenn Sie SRT/VTT-Ausgabe benötigen – nurwhisper-1unterstützt diese Formate - Erwarten, dass
gpt-4o-transcribe-diarizePrompts oder Logprobs unterstützt (tut es nicht) - Verwenden des Übersetzungs-Endpunkts für englische Audioinhalte (er übersetzt nur Nicht-Englisch in Englisch)
- Nichtbereitstellung des vorherigen Chunk-Kontexts beim Transkribieren aufgeteilter Dateien (reduziert die Genauigkeit an den Grenzen)
Tücken und Randfälle:
- Der
prompt-Parameter ist beiwhisper-1auf etwa 224 Token begrenzt. Längere Prompts werden abgeschnitten. whisper-1kann für stille oder nahezu stille Audioabschnitte Text halluzinieren. Verwenden Sieno_speech_probausverbose_json, um dies zu erkennen.gpt-4o-transcribeundgpt-4o-mini-transcribeunterstützen nur die Antwortformatejsonundtext– nichtsrt,vttoderverbose_json.- Der
language-Parameter verwendet ISO 639-1-Codes (z. B."en","fr","ja"). Das Setzen verbessert die Genauigkeit bei kurzem Audio. - Unterstützte Dateiformate: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Andere Formate müssen zuerst konvertiert werden.
gpt-4o-transcribe-diarizekennzeichnet Sprecher als „A“, „B“, „C“, sofern Sie nichtknown_speaker_namesundknown_speaker_referencesmit kurzen Audioclips angeben.- Der Übersetzungs-Endpunkt unterstützt nur
whisper-1und gibt nur Englisch aus – es gibt keine Möglichkeit, über diese API in andere Sprachen zu übersetzen. - Streaming-Transkription gibt
transcript.text.delta-Ereignisse mit einerdelta-String-Eigenschaft sowie ein abschließendestranscript.text.done-Ereignis aus.
</red_flags>
<critical_reminders>
KRITISCHE ERINNERUNGEN
**
…
[aus Platzgründen gekürzt]