Communitygithub.com

OpenAI Whisper Pattern

Sprache-zu-Text-Transkription und Übersetzung über die OpenAI Audio API – Modelle, Antwortformate, Zeitstempel, Prompting, Streaming, Chunking und Diarisierung

Was ist OpenAI Whisper Pattern?

Diese Fertigkeit beschreibt die Nutzung der OpenAI Audio API zur Transkription und Übersetzung von Audioinhalten. Sie deckt alle relevanten Modelle (`whisper-1`, `gpt-4o-transcribe`, `gpt-4o-mini-transcribe`, `gpt-4o-transcribe-diarize`) und deren spezifische Fähigkeiten ab, wie die Wahl des richtigen Modells basierend auf Genauigkeit, Kosten und Ausgabeformat. Die Dokumentation erklärt, wie man große Audiodateien (>25 MB) in sinnvolle Abschnitte aufteilt, um die Kontextintegrität zu wahren, und wie man Streaming-Transkriptionen sowie die Erkennung mehrerer Sprecher (Diarisierung) implementiert. Sie betont die Bedeutung des `prompt`-Parameters zur Verbesserung der Erkennungsgenauigkeit für Fachbegriffe, Akronyme und Formatierungsstile, und warnt vor häufigen Fehlern wie der Verwendung von `whisper-1` mit Streaming oder der Vernachlässigung von `response_format: verbose_json` bei Zeitstempeln. Die Anleitung ist plattformunabhängig und richtet sich an Entwickler, die die OpenAI Audio API in Anwendungen für Meetings, Untertitel, Videobearbeitung oder mehrsprachige Transkription integrieren möchten.

Funktioniert mit✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/ai-llm/api-ai-openai-whisper

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

OpenAI Whisper Patterns

Kurzanleitung: Verwenden Sie client.audio.transcriptions.create() für Sprache-zu-Text und client.audio.translations.create() für nicht-englisches Audio in englischen Text. Wählen Sie gpt-4o-transcribe für höchste Genauigkeit, gpt-4o-mini-transcribe für Kosteneffizienz, whisper-1 für Zeitstempel/SRT/VTT oder gpt-4o-transcribe-diarize für Sprecheridentifikation. Dateien müssen unter 25 MB groß sein – chunkieren Sie größere Dateien. Verwenden Sie prompt, um Wortschatz und Stil zu steuern. Streaming ist über stream: true für progressive Ausgabe bei gpt-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


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:

  1. Die Modellauswahl ist wichtig – gpt-4o-transcribe liefert die höchste Genauigkeit mit niedrigeren Halluzinationsraten. whisper-1 ist das einzige Modell, das SRT/VTT/verbose_json mit Zeitstempeln unterstützt. gpt-4o-transcribe-diarize fügt die Sprecheridentifikation hinzu.
  2. 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.
  3. Prompting verbessert die Genauigkeit – Der prompt-Parameter steuert Wortschatz, Akronyme und Formatierungsstil. Es gibt keine Anweisungen – es liefert Kontext, den das Modell abgleicht.
  4. Das Antwortformat bestimmt die verfügbaren Funktionen – Zeitstempel erfordern verbose_json bei whisper-1. Diarisierung erfordert diarized_json. SRT/VTT sind nur bei whisper-1 verfü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

Funktionwhisper-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
Antwortformatejson, text, srt, vtt, verbose_jsonjson, textjson, textjson, text, diarized_json
ZeitstempelWort + SegmentNeinNeinNein
StreamingNeinJaJaNein
Prompt-UnterstützungJa (224 Tokens)JaJaNein
LogprobsNeinJaJaNein
SprechermarkierungenNeinNeinNeinJa
SprachparameterJaJaJaJa

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_granularities ohne response_format: "verbose_json" bei whisper-1 (wird stillschweigend ignoriert)
  • Senden von Dateien größer als 25 MB (API gibt Fehler zurück)
  • Verwenden von gpt-4o-transcribe-diarize ohne chunking_strategy bei Audio > 30 Sekunden (API gibt Fehler zurück)
  • Verwenden von stream: true mit whisper-1 (nicht unterstützt)

Probleme mit mittlerer Priorität:

  • Verwenden von whisper-1, wenn gpt-4o-transcribe eine 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 – nur whisper-1 unterstützt diese Formate
  • Erwarten, dass gpt-4o-transcribe-diarize Prompts 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 bei whisper-1 begrenzt. Längere Prompts werden abgeschnitten.
  • whisper-1 kann für stille oder nahezu stille Audio-Segmente Text halluzinieren. Verwenden Sie no_speech_prob von verbose_json, um dies zu erkennen.
  • gpt-4o-transcribe und gpt-4o-mini-transcribe unterstützen nur die Antwortformate json und text – nicht srt, vtt oder verbose_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-diarize kennzeichnet Sprecher als "A", "B", "C", es sei denn, Sie geben known_speaker_names und known_speaker_references mit kurzen Audio-Clips an.
  • Der Übersetzungsendpunkt unterstützt nur whisper-1 und 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 einer delta-String-Eigenschaft, plus ein abschließendes transcript.text.done-Ereignis.

</red_flags>


<critical_reminders>

KRITISCHE ERINNERUNGEN

…

</critical_reminders>

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Verwandte Skills