Zum Hauptinhalt springen
Deutsch— Sprache auswählen
Menü

Ihr erster Transkriptionsanruf

Lektion 5 von 16 Aktualisiert am 3. November 2026 Entwickler
Auf dieser Seite
  1. Ihr erstes Transkript mit Voxtral
  2. Umgebung vorbereiten
  3. Lokale Datei transkribieren
  4. Transkribieren von einer URL
  5. Übergang zu einer robusten Version
  6. Was die Antwort enthält
  7. Kernaussagen

Kurs aktualisiert am 3. November 2026 für Voxtral 3, basierend auf Mistrals Leitfaden Migrate from Voxtral 2: 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 entfernt 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 (die Rückgabe von word führt zu einem 400-Fehler), die Sprechererkennung ist in Echtzeit möglich, die Einstellungen für Echtzeit-Sitzungen werden nach dem ersten Audio-Chunk gesperrt und context_bias-Eingaben sind frei formatiert (Phrasen mit Leerzeichen). Quellen: Migrate from Voxtral 2 · Speech to Text.

Ihr erstes Transkript mit Voxtral

Genug Theorie. In dieser Lektion führen Sie Ihren ersten vollständigen Aufruf der Offline-Transkriptions-API durch: Eine lokale Audiodatei wird an Voxtral Mini Transcribe 3 gesendet und das zurückgegebene Text wird verarbeitet. Der Code passt in wenigen Zeilen, wir bauen jedoch darauf auf, um eine robuste Version für den unüberwachten Betrieb zu erstellen.

Umgebung vorbereiten

Das Mistral SDK wird mit einem einzigen Befehl installiert. Der folgende Verifizierungsschritt spart Ihnen später die Suche nach einem Importfehler.

# Mistral SDK installieren
pip install mistralai

# Installation verifizieren
python -c "from mistralai.client import Mistral; print('SDK installiert')"

Sie benötigen einen Mistral API-Schlüssel. Erstellen Sie einen unter console.mistral.ai und speichern Sie ihn in einer Umgebungsvariable, statt ihn im Code festzuhalten:

export MISTRAL_API_KEY="ihre-api-schlüssel-hier"

Lokale Datei transkribieren

Hier ist der vollständige Code, um eine lokale Audiodatei zu transkribieren:

import os
from mistralai.client import Mistral

# Client initialisieren
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Audiodatei öffnen und transkribieren
with open("mon_audio.mp3", "rb") as f:
    response = client.audio.transcriptions.complete(
        model="voxtral-mini-transcribe-3",
        file={"content": f, "file_name": "mon_audio.mp3"}
    )

# Ergebnis anzeigen
print("=== Transkription ===")
print(response.text)

Das ist es. Mit vier Zeilen aktiven Code erhalten Sie das vollständige Transkript Ihrer Audiodatei.

Wir gehen diese vier Zeilen durch. Mistral(api_key=...) erstellt den Client mit Ihrem API-Schlüssel; dies ist das Objekt, das Sie für alle nachfolgenden Aufrufe wiederverwenden. open("mon_audio.mp3", "rb") öffnet die Datei im binären Modus, was für Audio zwingend erforderlich ist – das Auslassen des b führt zu einem Decodierungsfehler, der schwer zu interpretieren ist. Der Parameter file={"content": f, "file_name": "..."} erwartet ein Wörterbuch, das das Dateiojekt und dessen Namen enthält; dieser Name ist nicht dekorativ, er hilft dem Server, das Format zu erkennen. Schließlich enthält response.text das vollständige Transkript als Zeichenkette.

Transkribieren von einer URL

Wenn Ihre Audiodatei bereits online gehostet ist, verwenden Sie file_url statt file:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/mon_audio.mp3"
)

print(response.text)

Die URL muss öffentlich zugänglich sein. Der Mistral-Server lädt die Datei direkt herunter, wodurch das Routing des Audios durch Ihre Maschine vermieden wird, wenn es bereits in der Cloud liegt – eine erhebliche Bandbreiteneinsparung für einen Katalog von mehreren hundert Dateien.

Übergang zu einer robusten Version

Das minimale Skript funktioniert für einen Test. In der Produktion müssen Sie fehlende Dateien, unerwartete Formate, fehlende Schlüssel und Netzwerkfehler behandeln. Das folgende Skript führt diese Prüfungen vor dem Aufruf durch und speichert das Ergebnis.

import os
import sys
from pathlib import Path
from mistralai.client import Mistral

def transcrire_audio(chemin_fichier: str) -> str:
    """Transkribiert eine Audiodatei mit Voxtral Mini Transcribe 3."""

    # Prüfen, ob die Datei existiert
    fichier = Path(chemin_fichier)
    if not fichier.exists():
        raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")

    # Erweiterung prüfen
    extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
    if fichier.suffix.lower() not in extensions_valides:
        raise ValueError(
            f"Format non supporté : {fichier.suffix}. "
            f"Formats valides : {', '.join(extensions_valides)}"
        )

    # Größe prüfen (praktisches Limit: ~200 MB)
    taille_mo = fichier.stat().st_size / (1024 * 1024)
    if taille_mo > 200:
        print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")

    # Client initialisieren
    api_key = os.environ.get("MISTRAL_API_KEY")
    if not api_key:
        raise EnvironmentError("Variable MISTRAL_API_KEY non définie")

    client = Mistral(api_key=api_key)

    # Transkribieren
    try:
        with open(chemin_fichier, "rb") as f:
            response = client.audio.transcriptions.complete(
                model="voxtral-mini-transcribe-3",
                file={"content": f, "file_name": fichier.name}
            )
        return response.text
    except Exception as e:
        raise RuntimeError(f"Erreur de transcription : {e}")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Usage : python transcrire.py <fichier_audio>")
        sys.exit(1)

    chemin = sys.argv[1]
    print(f"Transcription de : {chemin}")
    print("-" * 50)

    texte = transcrire_audio(chemin)
    print(texte)

    # In Textdatei speichern
    sortie = Path(chemin).stem + "_transcription.txt"
    Path(sortie).write_text(texte, encoding="utf-8")
    print(f"\nTranscription sauvegardée dans : {sortie}")

Führen Sie es aus dem Terminal aus, indem Sie den Dateipfad übergeben:

python transcribe.py meeting_march15.mp3

Das Skript prüft die Datei, transkribiert sie, zeigt das Ergebnis an und speichert es automatisch in einer .txt-Datei mit dem gleichen Basennamen. Sie haben nun das Gerüst für die Batch-Verarbeitung: Schleifen Sie über ein Verzeichnis, und Ihre Audioarchiv wird zu einer durchsuchbaren Textarchiv.

Was die Antwort enthält

Das response-Objekt beschränkt sich nicht nur auf Text. Es liefert auch die Dauer der verarbeiteten Audio und die vom Modell erkannte Sprache – zwei nützliche Informationen für die Protokollierung Ihrer Jobs und zur Erkennung von Dateien, die nicht in der erwarteten Sprache sind.

# Vollständiger Text
print(response.text)

# Audiolaufzeit (in Sekunden)
print(f"Durée : {response.duration:.1f}s")

# Erkannte Sprache
print(f"Langue : {response.language}")

Der beste Weg, um die Qualität des Modells einzuschätzen, ist ein Test mit Ihrer eigenen Stimme. Aufnehmen Sie eine Sprachnachricht mit einer Länge von dreißig Sekunden bis zwei Minuten, führen Sie das obige Skript aus und vergleichen Sie das Ergebnis Wort für Wort mit dem, was Sie gesagt haben: Sie werden sofort sehen, wo die seltenen Fehler liegen, fast immer bei Eigennamen. Wiederholen Sie dann den Vorgang mit einer Datei in einer anderen Sprache, ohne den Code zu ändern, um die automatische Spracherkennung in Aktion zu beobachten.

Kernaussagen

  • Der minimale Aufruf erfordert 4 Zeilen: Client, Datei öffnen, API-Aufruf, Ergebnis lesen
  • Zwei Sendemodi: lokale Datei (file) oder URL (file_url)
  • Der Dateiname im file-Wörterbuch hilft bei der Formaterkennung
  • In der Produktion Fehlerbehandlung hinzufügen (fehlende Datei, ungültiges Format, Netzwerkfehler)
  • response.text enthält immer das vollständige Transkript als Zeichenkette