Tvoj prvi klic za prepis
Na tej strani
Tečaj posodobljen 3. novembra 2026 za Voxtral 3, na podlagi Mistralovega vodnika Migrate from Voxtral 2: modeli Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, ki so bili opuščeni 31. oktobra 2026 in odstranjeni 30. aprila 2027, so v primerih zamenjani zvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3invoxtral-mini-tts-3-0. Ključne spremembe: časovni žigi so samo po segmentih (wordvrne napako 400), določanje govorcev je mogoče v realnem času, nastavitve seje v realnem času so zaklenjene po prvem zvočnem delčku, vnosicontext_biaspa so v prosti obliki (fraze s presledki). Viri: Migrate from Voxtral 2 · Speech to Text.
Tvoj prvi prepis z Voxtralom
Dovolj teorije. V tej lekciji boš opravil svoj prvi popoln klic do API-ja za offline prepis: lokalna zvočna datoteka gre do Voxtral Mini Transcribe 3, ti pa obdelaš vrnjeno besedilo. Koda zavzame le nekaj vrstic, nato pa jo bomo nadgradili v robustno različico, primerno za samodejno delovanje.
Priprava okolja
Mistral SDK namestiš z enim samim ukazom. Korak preverjanja, ki sledi, ti prihrani kasnejše iskanje napak pri uvozu.
# Namesti Mistral SDK
pip install mistralai
# Preveri namestitev
python -c "from mistralai.client import Mistral; print('SDK installed')"
Potreboval boš ključ API za Mistral. Ustvari ga na console.mistral.ai in ga shrani v okoljsko spremenljivko, namesto da bi ga vgradil v kodo:
export MISTRAL_API_KEY="your-api-key-here"
Prepis lokalne datoteke
Tukaj je celotna koda za prepis lokalne zvočne datoteke:
import os
from mistralai.client import Mistral
# Inicializiraj odjemalca
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Odpri in prepiši zvočno datoteko
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"}
)
# Prikaži rezultat
print("=== Transcription ===")
print(response.text)
To je vse. S štirimi vrsticami aktivne kode dobiš celoten prepis svoje zvočne datoteke.
Pojdimo skozi te štiri vrstice. Mistral(api_key=...) ustvari odjemalca s tvojim ključem API; to je objekt, ki ga boš ponovno uporabil za vse nadaljnje klice. open("mon_audio.mp3", "rb") odpre datoteko v binarnem načinu, kar je za zvok obvezno – izpuščanje b povzroči napako pri dekodiranju, ki jo je težko razumeti. Parameter file={"content": f, "file_name": "..."} pričakuje slovar, ki vsebuje objekt datoteke in njeno ime; to ime ni le okras, saj strežniku pomaga zaznati format. Končno, response.text vsebuje celoten prepis kot niz.
Prepis iz URL-ja
Če je tvoja zvočna datoteka že gostovana na spletu, uporabi file_url namesto 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)
URL mora biti javno dostopen. Strežnik Mistral bo datoteko prenesel neposredno, kar se izogne usmerjanju zvoka skozi tvoj stroj, ko je ta že v oblaku – to je znatna prihranek pasovne širine za katalog več sto datotek.
Prehod na robustno različico
Minimalni skript deluje za test. V produkcijskem okolju moraš obravnavati manjkajoče datoteke, nepričakovane formate, manjkajoče ključe in omrežne napake. Naslednji skript opravi te preverke pred klicem, nato pa shrani rezultat.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Prepiše zvočno datoteko z Voxtral Mini Transcribe 3."""
# Preveri, ali datoteka obstaja
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")
# Preveri končnico
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)}"
)
# Preveri velikost (praktična omejitev: ~200 MB)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")
# Inicializiraj odjemalca
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)
# Prepiši
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)
# Shrani v besedilno datoteko
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Zaženi ga iz terminala tako, da podáš pot do datoteke:
python transcribe.py meeting_march15.mp3
Skript preveri datoteko, jo prepiše, prikaže rezultat in samodejno shrani v datoteko .txt z istim osnovnim imenom. Zdaj imaš ogrodje za serijsko obdelavo: zanka čez mapo in tvoj zvočni arhiv postane arhiv besedil, ki jih je mogoče iskati.
Kaj vsebuje odgovor
Objekt response ni omejen le na besedilo. Zagotavlja tudi trajanje obdelanega zvoka in jezik, ki ga je prepoznal model – dva koristna podatka za beleženje opravil in zaznavanje datotek, ki niso v pričakovanem jeziku.
# Celotno besedilo
print(response.text)
# Trajanje zvoka (v sekundah)
print(f"Durée : {response.duration:.1f}s")
# Zaznan jezik
print(f"Langue : {response.language}")
Najboljši način za oceno kakovosti modela je, da ga preizkusiš na svojem glasu. Posnemi glasovno sporočilo, dolgo od trideset sekund do dveh minut, zaženi zgornji skript in primerjaj rezultat besedo za besedo s tem, kar si rekel: takoj boš videl, kje so redke napake, ki so skoraj vedno na lastnih imenih. Nato ponovi vajo z datoteko v drugem jeziku, ne da bi spremenil kodo, da bi opazoval samodejno zaznavanje jezika v akciji.
Ključne ugotovitve
- Minimalni klic zahteva 4 vrstice: odjemalec, odprtje datoteke, klic API-ja, branje rezultata
- Dva načina pošiljanja: lokalna datoteka (
file) ali URL (file_url) - Ime datoteke v slovarju
filepomaga pri zaznavanju formata - V produkcijskem okolju dodaj obravnavo napak (manjkajoča datoteka, neveljaven format, omrežna napaka)
response.textvedno vsebuje celoten prepis kot niz