OpenAI Whisper Patterns
Kurzanleitung: Verwenden Sie
client.audio.transcriptions.create()für Sprache-zu-Text undclient.audio.translations.create()für nicht-englisches Audio 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-diarizefür Sprecheridentifikation. Dateien müssen unter 25 MB groß 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 der Verwendung dieser Fertigkeit
Der gesamte Code muss den Projektkonventionen in CLAUDE.md folgen (kebab-case, benannte Exporte, Importreihenfolge,
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 Sprechermarkierungen)
(Sie MÜSSEN Audiodateien, die größer als 25 MB sind, vor dem Senden an die API aufteilen – 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 dies)
</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 verwenden:
- Transkription von Audiodateien (Besprechungen, Interviews, Podcasts, Sprachnotizen) in Text
- Übersetzung von nicht-englischem Audio in englischen Text
- Generierung von Untertiteln im SRT- oder VTT-Format aus Audio
- Abrufen von Wort- oder Segment-Zeitstempeln für die Videobearbeitung
- Identifizieren von Sprechern in Audio mit mehreren Sprechern (Diarisierung)
- Streaming von Transkriptionsergebnissen progressiv, während das Modell Audio verarbeitet
Abgedeckte Schlüsselmuster:
- 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 (Wort-Ebene, Segment-Ebene) 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 verwenden:
- Text-zu-Sprache (TTS) – verwenden Sie die OpenAI TTS API (
client.audio.speech.create()) - Echtzeit-Zweiwege-Sprachgespräche – verwenden Sie die OpenAI Realtime API
- Transkription mit Nicht-OpenAI-Anbietern – verwenden Sie ein anbieterunabhängiges Speech 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:
- Die 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. - Die Dateigröße ist die wichtigste Einschränkung – Das 25-MB-Limit bedeutet, dass Sie längeres Audio aufteilen müssen. Teilen Sie an Satzgrenzen, um den Kontext zu erhalten.
- Prompting verbessert die Genauigkeit – Der
prompt-Parameter steuert Wortschatz, Akronyme und Formatierungsstil. Es gibt keine Anweisungen – es liefert Kontext, den 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 verwenden:
- Sie benötigen eine genaue Transkription von aufgezeichneten 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 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: Basis-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 whisper-1 nicht mit verbose_json, wenn Sie nur einfachen Text benötigen – es verursacht Overhead und hat höhere Halluzinationsraten. Siehe core.md für vollständige Beispiele.
Muster 2: Modellauswahl
Jedes Modell hat unterschiedliche Fähigkeiten und Kompromisse.
Was benötigen Sie?
+-- Höchste Genauigkeit, einfacher Text -> gpt-4o-transcribe
+-- Kosteneffizient, einfacher Text -> 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 Tokens) | Ja | Ja | Nein |
| Logprobs | Nein | Ja | Ja | Nein |
| Sprechermarkierungen | 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 Wortschatzkontext 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 (Ende des vorherigen Transkripts übergeben), Beibehaltung von Füllwörtern, Schreibstilführung. Siehe core.md für detaillierte Wortschatzbeispiele.
Muster 4: Chunking großer Dateien
Audiodateien, die 25 MB überschreiten, müssen vor der Transkription aufgeteilt werden. Teilen Sie an Satzgrenzen (z.B. mit ffmpeg), um den Kontext zu erhalten. Übergeben Sie das Ende des vorherigen Transkripts als prompt für die Kontinuität über Chunks hinweg.
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// Split with ffmpeg: ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Then transcribe sequentially, passing previous context via prompt
Siehe core.md für die vollständige Chunking-Implementierung mit Größenvalidierung und Kontexterhaltung.
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 stream: true NICHT 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);
}
Siehe core.md für vollständige Streaming- und Logprob-Beispiele.
Muster 6: Übersetzung ins Englische
Übersetzen Sie nicht-englisches Audio in englischen Text. Nur whisper-1 wird über audio.translations.create() unterstützt. Verwenden Sie für die gleichsprachige Transkription 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),
});
Siehe core.md für vollständige Übersetzungsbeispiele inklusive Wortschatz-Prompting.
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 lange Audio-Clips als Data-URLs) angeben, um Segmente bekannten Sprechern zuzuordnen (bis zu 4). Siehe core.md für vollständige Diarisierungsbeispiele.
<decision_framework>
Entscheidungsrahmen
Welches Modell wählen
Was benötigen Sie von der Transkription?
+-- Nur Text (höchste Genauigkeit) -> gpt-4o-transcribe
+-- Nur Text (kostensensibel) -> 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?
+-- Einfacher Text-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)
+-- Sprechermarkierte 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:
- Verwenden von
timestamp_granularitiesohneresponse_format: "verbose_json"beiwhisper-1(wird stillschweigend ignoriert) - Senden von Dateien größer als 25 MB (API gibt Fehler zurück)
- Verwenden von
gpt-4o-transcribe-diarizeohnechunking_strategybei Audio > 30 Sekunden (API gibt Fehler zurück) - Verwenden von
stream: truemitwhisper-1(nicht unterstützt)
Probleme mit mittlerer Priorität:
- Verwenden 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 (Automatische Erkennung kann bei kurzem oder verrauschtem Audio falsch sein) - Verwenden 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 Grenzen)
Häufige Fehler:
- Den
prompt-Parameter als Anweisung behandeln ("bitte sorgfältig transkribieren") – er ist Kontext für Wortschatz- und Stilabgleich - Verwenden 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 Übersetzungsendpunkts für englisches Audio (er übersetzt nur nicht-Englisch ins Englische)
- Nichtbereitstellen des vorherigen Chunk-Kontexts beim Transkribieren geteilter Dateien (reduziert Genauigkeit an Grenzen)
Fallstricke & Randfälle:
- Der
prompt-Parameter ist auf ungefähr 224 Tokens beiwhisper-1begrenzt. Längere Prompts werden abgeschnitten. whisper-1kann für stille oder nahezu stille Audio-Segmente Text halluzinieren. Verwenden Sieno_speech_probvonverbose_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", es sei denn, Sie gebenknown_speaker_namesundknown_speaker_referencesmit kurzen Audio-Clips an.- Der Übersetzungsendpunkt unterstützt nur
whisper-1und gibt nur Englisch aus – es gibt keine Möglichkeit, über diese API in andere Sprachen zu übersetzen. - Streaming-Transkription emittiert
transcript.text.delta-Ereignisse mit einerdelta-String-Eigenschaft, plus ein abschließendestranscript.text.done-Ereignis.
</red_flags>
<critical_reminders>
KRITISCHE ERINNERUNGEN
…
</critical_reminders>