Tvá první transkripční žádost
Na této stránce
Kurz aktualizován 3. listopadu 2026 pro Voxtral 3 na základě průvodce Mistralu Migrate from Voxtral 2: Modely Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), které byly zastaralé k 31. říjnu 2026 a odstraněny k 30. dubnu 2027, jsou v příkladech nahrazeny modelyvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Klíčové změny: časová razítka jsou pouze pro segmenty (wordvrací chybu 400), diarizace je možná v reálném čase, nastavení relace v reálném čase jsou uzamčena po prvním zvukovém úseku a vstupycontext_biasjsou volného formátu (fráze s mezerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Tvá první transkripce s Voxtralem
Teorie bylo dost. V této lekci provedeš svou první kompletní žádost k API pro offline transkripci: místní zvukový soubor odešleš do Voxtral Mini Transcribe 3 a zpracuješ vrácený text. Kód se vejde do několika řádků, ale následně ho rozšíříme na robustní verzi vhodnou pro automatizovaný provoz.
Příprava prostředí
SDK Mistral nainstaluješ jediným příkazem. Následný ověřovací krok tě ušetří pozdějšího hledání chyb při importu.
# Instalace SDK Mistral
pip install mistralai
# Ověření instalace
python -c "from mistralai.client import Mistral; print('SDK installed')"
Budeš potřebovat klíč API Mistral. Vytvoř si ho na console.mistral.ai a ulož jej do proměnné prostředí místo toho, abys ho vkládal přímo do kódu:
export MISTRAL_API_KEY="your-api-key-here"
Transkripce místního souboru
Zde je kompletní kód pro transkripci místního zvukového souboru:
import os
from mistralai.client import Mistral
# Inicializace klienta
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Otevření a transkripce zvukového souboru
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"}
)
# Zobrazení výsledku
print("=== Transcription ===")
print(response.text)
To je vše. Ve čtyřech řádcích aktivního kódu získáš plnou transkripci svého zvukového souboru.
Pojďme si tyto čtyři řádky rozebrat. Mistral(api_key=...) vytvoří klienta s tvým klíčem API; toto je objekt, který budeš znovu používat pro všechny následující volání. open("mon_audio.mp3", "rb") otevře soubor v binárním režimu, což je pro zvuk povinné – vynechání b způsobí chybu dekódování, kterou je obtížné interpretovat. Parametr file={"content": f, "file_name": "..."} očekává slovník obsahující objekt souboru a jeho název; tento název není jen dekorativní, pomáhá serveru detekovat formát. Nakonec response.text obsahuje celou transkripci jako řetězec.
Transkripce z URL
Pokud je tvůj zvukový soubor již hostován online, použij místo file parametr file_url:
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)
URL musí být veřejně přístupná. Server Mistral si soubor stáhne přímo, což avoids směrování zvuku přes tvůj stroj, když je již v cloudu – významná úspora šířky pásma pro katalog několika set souborů.
Přechod na robustní verzi
Minimální skript funguje pro test. V produkčním prostředí musíš ošetřit chybějící soubory, neočekávané formáty, chybějící klíče a chyby sítě. Následující skript provede tyto kontroly před voláním a poté výsledek uloží.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Transcribes an audio file with Voxtral Mini Transcribe 3."""
# Kontrola existence souboru
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")
# Kontrola přípony
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)}"
)
# Kontrola velikosti (praktický limit: ~200 MB)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")
# Inicializace klienta
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)
# Transkripce
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)
# Uložení do textového souboru
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Spusť jej z terminálu předáním cesty k souboru:
python transcribe.py meeting_march15.mp3
Skript zkontroluje soubor, provede transkripci, zobrazí výsledek a automaticky jej uloží do souboru .txt se stejným základním názvem. Nyní máš kostru pro dávkové zpracování: projdi adresář smyčkou a tvůj zvukový archiv se stane prohledatelným textovým archivem.
Co odpověď obsahuje
Objekt response není omezen pouze na text. Poskytuje také délku zpracovaného zvuku a jazyk rozpoznaný modelem – dvě užitečné informace pro logování tvých úloh a detekci souborů, které nejsou v očekávaném jazyce.
# Celý text
print(response.text)
# Délka zvuku (v sekundách)
print(f"Durée : {response.duration:.1f}s")
# Detekovaný jazyk
print(f"Langue : {response.language}")
Nejlepším způsobem, jak posoudit kvalitu modelu, je otestovat ho na vlastním hlasu. Nahraj hlasovou zprávu v délce třiceti sekund až dvou minut, spusť výše uvedený skript a porovnej výsledek slovo od slova s tím, co jsi řekl: okamžitě uvidíš, kde leží vzácné chyby, téměř vždy u vlastních jmen. Poté cvičení zopakuj se souborem v jiném jazyce, aniž bys měnil kód, abys pozoroval automatickou detekci jazyka v akci.
Klíčové poznatky
- Minimální volání vyžaduje 4 řádky: klient, otevření souboru, volání API, přečtení výsledku
- Dva způsoby odeslání: místní soubor (
file) nebo URL (file_url) - Název souboru ve slovníku
filepomáhá s detekcí formátu - V produkci přidej ošetření chyb (chybějící soubor, neplatný formát, chyba sítě)
response.textvždy obsahuje celou transkripci jako řetězec