Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Audiodateien transkribieren

Wandle aufgezeichnete Sprache in Text um.

Nutze die Dateitranskription, wenn die Aufnahme abgeschlossen ist oder du einen zeitlich begrenzten Audioausschnitt in einer Anfrage sendest. Lade die Audiodaten hoch, um das fertige Transkript zu erhalten. Du kannst den Text auch streamen, während das Modell die Datei verarbeitet.

Beginne mit gpt-transcribe. Dieses Modell wird empfohlen, um aufgezeichnete Sprache in der Originalsprache zu transkribieren. Die folgenden Beispiele zur Zuordnung von Redebeiträgen, zu Zeitstempeln für einzelne Wörter und zu Untertitelformaten verwenden veraltete Modelle.

whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize und /v1/audio/translations sind veraltet und werden am 26. Februar 2027 abgeschaltet. Lies den Hinweis zur Einstellung und wähle ein aktuelles Verfahren zur Transkription. Die folgenden Beispiele zeigen, welche speziellen Funktionen bestehende Integrationen bis zur Abschaltung nutzen können.

Dateien dürfen bis zu 25 MB groß sein. Zu den unterstützten Eingabeformaten gehören flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav und webm.

Wenn laufend Audiodaten von einem Mikrofon, aus einem Anruf oder einem Medienstream eintreffen, nutze die Echtzeittranskription.

Schnellstart

Transkriptionen

Sende die Audiodatei an /v1/audio/transcriptions und gib gpt-transcribe als Modell an.

Audiodatei transkribieren
from openai import OpenAI

client = OpenAI()
audio_file = open("audio.wav", "rb")

transcription = client.audio.transcriptions.create(
    model="gpt-transcribe", file=audio_file
)

print(transcription.text)

Das Modell gibt das Transkript und die erkannten Sprachen im JSON-Format zurück.

{
  "text": "Bonjour, pouvez-vous m'entendre ?",
  "languages": [{ "code": "fr" }]
}

Wenn das Modell die Sprache nicht zuverlässig erkennt, gibt es "languages": [] zurück. Alle Felder für Anfragen und Antworten findest du in der Referenz zur Audio-API.

Kontext für die Transkription angeben

Verwende prompt, keywords und languages mit gpt-transcribe, damit das Modell Fachbegriffe und mehrsprachige Aufnahmen genauer transkribiert.

Kontext und Hinweise zu den Sprachen angeben
from openai import OpenAI

client = OpenAI()

with open("meeting.wav", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        prompt="A customer support call about a premium plan and account AC-42.",
        extra_body={
            "keywords": ["premium plan", "AC-42", "billing"],
            "languages": ["en", "fr"],
        },
    )

print(transcription.text)
  • Beschreibe mit prompt den Kontext der Aufnahme in freier Form.
  • Gib mit keywords die genauen Begriffe an, die du in der Aufnahme erwartest.
  • Gib mit languages die erwarteten Eingabesprachen an.

Schlüsselwörter dienen als Hinweise. Sie müssen im Transkript nicht vorkommen. Gib nur relevante Begriffe an und prüfe, ob sie die Genauigkeit verbessern, ohne dass ungesprochene Begriffe im Transkript erscheinen.

Bei gpt-transcribe ersetzt languages das bisherige Feld language für eine einzelne Sprache. Sende nicht beide Felder. Schreibe jedes Schlüsselwort in eine einzige Zeile. Es darf weder < noch > noch einen Wagenrücklauf oder einen Zeilenvorschub enthalten. Die API lehnt die gesamte Anfrage ab, wenn sie eines dieser Zeichen findet oder wenn prompt die Längenbegrenzung des Modells überschreitet.

Sprecherzuordnung

Bestehende Integrationen können das veraltete Modell gpt-4o-transcribe-diarize bis zum 26. Februar 2027 nutzen, um zu erkennen, wer in welchem Abschnitt einer Aufnahme spricht. Das Modell ist auf die Zuordnung von Redebeiträgen spezialisiert. Für die gewöhnliche Dateitranskription wird es nicht empfohlen.

Fordere das Antwortformat diarized_json an, um Segmente mit den Metadaten speaker, start und end zu erhalten. Setze bei Aufnahmen von mehr als 30 Sekunden chunking_strategy auf "auto" oder gib für diesen Parameter eine Konfiguration zur Erkennung von Sprachaktivität an.

Optional kannst du mit known_speaker_names[] und known_speaker_references[] bis zu vier kurze Referenzaufnahmen angeben, um die Segmente bekannten Personen zuzuordnen. Verwende dafür Ausschnitte von 2 bis 10 Sekunden in einem der Eingabeformate, die für die eigentliche Audiodatei unterstützt werden. Wenn du mehrteilige Formulardaten verwendest, kodiere die Ausschnitte als Daten-URLs.

Redebeiträge in einer Besprechungsaufnahme zuordnen
import base64
from openai import OpenAI

client = OpenAI()


def to_data_url(path: str) -> str:
    with open(path, "rb") as fh:
        return "data:audio/wav;base64," + base64.b64encode(fh.read()).decode("utf-8")


with open("meeting.wav", "rb") as audio_file:
    transcript = client.audio.transcriptions.create(
        model="gpt-4o-transcribe-diarize",
        file=audio_file,
        response_format="diarized_json",
        chunking_strategy="auto",
        extra_body={
            "known_speaker_names": ["agent"],
            "known_speaker_references": [to_data_url("agent.wav")],
        },
    )

for segment in transcript.segments:
    print(segment.speaker, segment.text, segment.start, segment.end)

Bei stream=true enthält der Antwortstream mit Sprecherzuordnung für jedes abgeschlossene Segment ein Ereignis vom Typ transcript.text.segment. Ereignisse vom Typ transcript.text.delta enthalten das Feld segment_id, aber keine vorläufige Sprecherzuordnung. Erst wenn das Modell das Segment abschließt, ordnet es ihm eine Person zu.

Die Sprecherzuordnung ist über /v1/audio/transcriptions verfügbar. Sitzungen zur Echtzeittranskription unterstützen sie nicht.

Übersetzungen

Der veraltete Endpunkt /v1/audio/translations verwendet whisper-1, um abgeschlossene Audioaufnahmen ins Englische zu übersetzen. Er bleibt bis zum 26. Februar 2027 verfügbar. Bei der Transkription bleibt die Originalsprache der Aufnahme erhalten. Dieser Endpunkt gibt ausschließlich englischen Text zurück.

Wechsle zur Echtzeitübersetzung mit gpt-realtime-translate am Endpunkt /v1/realtime/translations. Dafür musst du eine Übersetzungssitzung starten, die Audiodaten als Stream senden und Übersetzungsereignisse verarbeiten. Für die Umstellung reicht es nicht aus, in einer Anfrage an /v1/audio/translations nur die Modell-ID zu ändern.

Unterstützte Sprachen

Verwende languages mit gpt-transcribe, wenn du weißt, welche Sprachen in der Aufnahme zu erwarten sind. Zu den unterstützten Formaten für Sprachcodes gehören:

  • Codes nach ISO 639-1 wie en, es und fr.
  • Ausgewählte Codes nach ISO 639-3 wie eng, spa, yue und cmn.
  • Regionale Gebietsschemacodes für zh wie zh-cn, zh-tw und zh-hk.

Die API lehnt nicht unterstützte oder falsch formatierte Sprachcodes ab. Die Antwort nennt außerdem alle Sprachen, die das Modell zuverlässig erkennt.

Für whisper-1 findest du die unterstützten Sprachen in der Sprachliste von Whisper. Whisper unterstützt 98 Sprachen. Die Genauigkeit variiert je nach Sprache. Bestehende Modelle, die nur einen Sprachhinweis akzeptieren, verwenden language anstelle von languages.

Zeitstempel

Bestehende Integrationen können das veraltete Modell whisper-1 bis zum 26. Februar 2027 für Zeitstempel auf Wort- oder Segmentebene nutzen. Mit dem Parameter timestamp_granularities[] erhältst du strukturierte Zeitstempeldaten für die Untertitelung und den Videoschnitt.

Optionen für Zeitstempel
from openai import OpenAI

client = OpenAI()
audio_file = open("speech.wav", "rb")

transcription = client.audio.transcriptions.create(
    file=audio_file,
    model="whisper-1",
    response_format="verbose_json",
    timestamp_granularities=["word"],
)

print(transcription.words)

Der Parameter timestamp_granularities[] ist nur für whisper-1 verfügbar.

Längere Aufnahmen

Die Transcriptions API akzeptiert Dateien bis zu 25 MB. Verwende für größere Aufnahmen ein komprimiertes Audioformat oder teile die Datei in Abschnitte von jeweils höchstens 25 MB auf. Trenne die Aufnahme möglichst an Satzgrenzen. Wenn du einen Satz teilst, kann Kontext verloren gehen und die Transkription ungenauer werden.

Zum Aufteilen der Aufnahme kannst du beispielsweise das quelloffene Python-Paket PyDub verwenden.

from pydub import AudioSegment

song = AudioSegment.from_wav("good_morning.wav")

# PyDub handles time in milliseconds
ten_minutes = 10 * 60 * 1000

first_10_minutes = song[:ten_minutes]

first_10_minutes.export("good_morning_10.wav", format="wav")

OpenAI übernimmt keine Garantie für die Nutzbarkeit oder Sicherheit von Drittanbietersoftware wie PyDub.

Prompts verwenden

Mit einem Prompt kannst du dem Modell helfen, Namen, Akronyme und Begriffe aus der Aufnahme zu erkennen und die gewünschte Formatierung zu verwenden. Kombiniere den Prompt bei gpt-transcribe mit den Parametern keywords und languages aus dem Abschnitt Kontext für die Transkription angeben.

Bestehende Integrationen mit gpt-4o-transcribe und gpt-4o-mini-transcribe unterstützen ebenfalls Prompts. gpt-4o-transcribe-diarize unterstützt keine Prompts.

Mit Prompts kannst du beispielsweise:

  • Produktnamen, Fachbegriffe und Akronyme korrekt transkribieren lassen.
  • Kontext aus einem früheren Abschnitt einer längeren Aufnahme übernehmen.
  • Zeichensetzung, Groß- und Kleinschreibung sowie Füllwörter beibehalten.
  • Das bevorzugte Schriftsystem für eine Sprache auswählen.

Bei whisper-1 sind Prompts auf 224 Token begrenzt und bieten weniger Steuerungsmöglichkeiten als beim empfohlenen Transkriptionsmodell. Wenn du für deinen Workflow Whisper benötigst, lies den Abschnitt Zuverlässigkeit verbessern.

Transkriptionen streamen

Bei der Dateitranskription kannst du den Text abschnittsweise als Stream empfangen, während das Modell eine abgeschlossene Aufnahme verarbeitet. Dafür brauchst du keine Echtzeitsitzung.

Transkription einer abgeschlossenen Audioaufnahme streamen

Setze stream=true, wenn du gpt-transcribe verwendest. Während das Modell die einzelnen Abschnitte der Aufnahme transkribiert, gibt die Transcriptions API Transkriptereignisse zurück.

Transkriptionen streamen
from openai import OpenAI

client = OpenAI()
audio_file = open("speech.wav", "rb")

stream = client.audio.transcriptions.create(
    model="gpt-transcribe",
    file=audio_file,
    stream=True,
)

for event in stream:
    print(event)

Während der Transkription sendet das Modell Ereignisse vom Typ transcript.text.delta. Anschließend gibt es das vollständige Transkript in einem abschließenden Ereignis vom Typ transcript.text.done zurück. Bei der Transkription mit Sprecherzuordnung und response_format="diarized_json" sendet das darauf spezialisierte Modell zusätzlich ein Ereignis vom Typ transcript.text.segment, sobald es ein Segment abschließt.

Bei gpt-transcribe enthält das abschließende Ereignis auch die erkannten Sprachen.

{
  "type": "transcript.text.done",
  "text": "Bonjour, pouvez-vous m'entendre ?",
  "languages": [{ "code": "fr" }]
}

Bestehende Integrationen mit gpt-4o-transcribe, gpt-4o-mini-transcribe und gpt-4o-transcribe-diarize unterstützen ebenfalls das Streaming von Dateitranskriptionen. whisper-1 unterstützt diese Funktion nicht.

Transkription einer laufenden Audioaufnahme streamen

Für Live-Audio von einem Mikrofon, aus einem Anruf oder einem Medienstream folge der Anleitung zur Echtzeittranskription anstelle des oben beschriebenen Verfahrens für Dateien. Die Anleitung beschreibt den aktuellen Ablauf einer Transkriptionssitzung und das empfohlene Echtzeitverfahren mit gpt-live-transcribe.

Zuverlässigkeit verbessern

Wenn du whisper-1 für Zeitstempel, Untertitel oder Übersetzungen verwendest, können die folgenden Verfahren helfen, seltene Wörter und Akronyme zuverlässiger zu erkennen. Für neue Integrationen zur allgemeinen Transkription beginne mit gpt-transcribe und gib stattdessen Kontext für die Transkription an.