Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Die Offline-Transkriptions-API

Lektion 4 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Der Transkriptions-Endpunkt
  2. Aufrufparameter
  3. Unterstützte Audioformate
  4. Antwortstruktur
  5. Parameterkombinationen
  6. Authentifizierung
  7. Kernaussagen

Kurs aktualisiert am 3. November 2026 für Voxtral 3, basierend auf Mistrals Migrate from Voxtral 2-Guide: Die Voxtral 2-Modelle (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), die am 31. Oktober 2026 veraltet und am 30. April 2027 zurückgezogen wurden, werden in den Beispielen durch voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 und voxtral-mini-tts-3-0 ersetzt. Wesentliche Änderungen: Zeitstempel sind segmentbasiert (word führt zu einem 400-Fehler), Echtzeit-Diarisierung ist unterstützt, Echtzeit-Sitzungseinstellungen werden nach dem ersten Audio-Chunk gesperrt, und context_bias-Einträge sind frei formatiert (Phrasen mit Leerzeichen). Quellen: Migrate from Voxtral 2 · Speech to Text.

Der Transkriptions-Endpunkt

Die Offline-Transkriptions-API von Mistral verwendet den Endpunkt /audio/transcriptions. Es handelt sich um eine synchrone API: Sie senden eine Audiodatei, die Anfrage bleibt während der Verarbeitung offen, und Sie erhalten das vollständige Transkript in der Antwort. Es gibt keine Task-ID zum Abfragen und keinen Webhook zur Konfiguration. Dies vereinfacht Ihren Code erheblich, aber Sie müssen für lange Dateien großzügige Timeouts vorsehen.

Bevor Sie mit dem Codieren beginnen, stellen Sie sicher, dass Sie drei Voraussetzungen erfüllen: ein Mistral-Plattformkonto (console.mistral.ai), einen aktiven API-Schlüssel und die Python-SDK installiert.

SDK installieren

pip install mistralai

Aufrufparameter

Alles läuft über client.audio.transcriptions.complete(). Zwei Parameter sind erforderlich, vier sind optional. Diese optionalen Parameter verwandeln eine rohe Transkription in ein nutzbares Ergebnis.

Erforderliche Parameter

  • model — Die Modell-Identifizierung. Für die Offline-Transkription verwenden Sie "voxtral-mini-transcribe-3" (empfohlen) oder eine festgelegte Version wie "voxtral-mini-transcribe-3".
  • file oder file_url — Die zu transkribierende Audiodatei. Sie haben zwei Optionen:
    • file: Ein Dictionary {"content": file_object, "file_name": "name.mp3"} für den direkten Upload.
    • file_url: Eine öffentliche URL, die auf die Audiodatei verweist.

Die Wahl zwischen file und file_url ist eine architektonische Entscheidung. Wenn Ihre Audioinhalte bereits an einem öffentlich zugänglichen Ort gespeichert sind, vermeidet file_url die Weiterleitung der Datei durch Ihren Server. Wenn die Datei von einem Benutzergerät oder einer privaten Speicherung stammt, ist ein direkter Upload notwendig.

Optionale Parameter

Vier optionale Einstellungen verändern die Natur der Ausgabe.

language erwartet einen ISO-Sprachcode, wie "fr" oder "en", und umgeht die automatische Erkennung. Erzwingen Sie dies für homogene Batches, wie z. B. ein Katalog von Interviews, die vollständig auf Französisch geführt wurden, um zu verhindern, dass ein kurzer englischer Abschnitt das Modell mitten in der Datei wechselt. Beachten Sie, dass dies inkompatibel mit timestamp_granularities ist.

timestamp_granularities nimmt die Liste ["segment"] an und löst die Rückgabe von Zeitstempeln segmentweise aus. Mit Voxtral 3 existiert die Granularität word nicht mehr und führt zu einem 400-Fehler. Dieser Parameter ermöglicht Untertiteldateien, die mit Video synchronisiert sind, oder indizierte Passagen in einer zweistündigen Konferenz.

diarize ist ein Boolean-Wert. Wenn auf True gesetzt, identifiziert das Modell die Sprecher und weist jedem Segment einen von ihnen zu. Für einen sechsköpfigen Exekutivausschuss ist dies der Unterschied zwischen einer anonymen Textwand und einem Bericht, bei dem jede Verpflichtung zuordenbar ist.

Schließlich akzeptiert context_bias eine Liste von Begriffen – ein einzelnes Wort oder eine Phrase mit Leerzeichen, wie z. B. ein Produktnamen –, um die Erkennung spezifischen Vokabulars zu verbessern. Die Anzahl der Einträge ist nicht mehr festgelegt, sie teilen sich jedoch das Kontextfenster mit dem Audio, daher halten Sie die Liste kurz. Eine Ingenieursbesprechung mit Begriffen wie “Kubernetes” und “GDPR” wird mit dieser Einstellung deutlich lesbarer.

Unterstützte Audioformate

Voxtral akzeptiert gängige Audioformate, und Sie werden selten vorherige Konvertierungen benötigen. Im Zweifel verweisen Sie auf die Seite Audio formats in der Dokumentation.

FormatCharakteristik
MP3Häufigstes Format, gute Kompression
WAVUnkomprimiert, maximale Qualität
FLACVerlustlose Kompression
OGGOffenes Format, gute Kompression
M4A / AACApple-Format, häufig auf Mobilgeräten
WEBMWeb-Format, häufig für Browseraufnahmen

Das kritische Limit ist das Kontextfenster des Modells, das zwischen dem Audio und dem context_bias-Vokabular geteilt wird. Eine Anfrage, die dieses Limit überschreitet, wird mit einem 400-Fehler abgelehnt; die API kürzt die Datei nicht. Bei sehr langen Dateien, wie z. B. einem tagelangen Seminar, teilen Sie diese vor dem Senden auf, vorzugsweise an Stillepunkten, um Sätze nicht mitten durchzuschneiden.

Antwortstruktur

Die Antwort enthält mindestens den transkribierten Text:

response.text          # Der vollständige transkribierte Text (str)

Wenn Sie Zeitstempel angefordert haben (timestamp_granularities), enthält die Antwort zusätzlich:

response.segments      # Liste von Segmenten mit Start, Ende, Text

Wenn Sie die Diarisierung aktiviert haben (diarize=True), enthält jedes Segment die Sprecheridentität:

segment.speaker_id        # Sprecher-Identifizierung (str)
segment.start          # Startzeit in Sekunden (float)
segment.end            # Endzeit in Sekunden (float)
segment.text           # Segment-Text (str)

Kurz gesagt, die Form des zurückgegebenen Objekts hängt von Ihrer Anfrage ab. Code, der über response.segments iteriert, ohne timestamp_granularities zu übergeben, wird fehlschlagen. Überprüfen Sie immer die Konsistenz zwischen Ihren Eingabeparametern und Ihrer Ausgabeverarbeitung.

Parameterkombinationen

Hier sind die fünf häufigsten gültigen Kombinationen, von einfach bis spezialisiert.

# Einfache Transkription (nur Text)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"}
)

# Mit erzwungener Sprache (keine Zeitstempel)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Mit Segment-Zeitstempeln
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Mit Diarisierung + Zeitstempeln
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Mit Kontext-Biasing
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/audio.mp3",
    context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)

Eine überraschende Einschränkung in Voxtral 2 war, dass language und timestamp_granularities nicht in derselben Anfrage verwendet werden konnten. Die Voxtral 3-Dokumentation erwähnt diese Einschränkung nicht mehr; überprüfen Sie dies vor der Nutzung mit einem Test.

Authentifizierung

Alle Anfragen erfordern einen gültigen API-Schlüssel, der an den Client-Konstruktor übergeben wird. In der Entwicklung reicht ein direktes Argument. In der Produktion verwenden Sie eine Umgebungsvariable, um zu verhindern, dass der Schlüssel in Ihrem Git-Repository landet.

from mistralai.client import Mistral

# Über direktes Argument
client = Mistral(api_key="your-api-key")

# Oder über Umgebungsvariable (empfohlen für Produktion)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Kernaussagen

  • Der Endpunkt /audio/transcriptions ist synchron: Senden Sie die Datei, erhalten Sie den Text.
  • Zwei Upload-Modi: direkter Upload (file) oder öffentliche URL (file_url).
  • Optionale Parameter: language, timestamp_granularities, diarize, context_bias.
  • In Voxtral 2 waren language und timestamp_granularities sich gegenseitig ausschließend; die Voxtral 3-Dokumentation erwähnt dies nicht mehr.
  • Gängige Audioformate werden unterstützt; das Limit ist das zwischen Audio und context_bias geteilte Kontextfenster (400-Fehler bei Überschreitung).
  • Diarisierung und Zeitstempel können kombiniert werden.