API za transkripcijo brez povezave
Na tej strani
Posodobitev tečaja z dne 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 umaknjeni 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), podprta je ločevanje govorcev v realnem času, nastavitve seje v realnem času so zaklenjene po prvem zvočnem delčku, vnosicontext_biaspa so prosto oblikovani (fraze s presledki). Viri: Migrate from Voxtral 2 · Speech to Text.
Končna točka za transkripcijo
Mistralov API za transkripcijo brez povezave uporablja končno točko /audio/transcriptions. Gre za sinhroni API: pošljete zvočno datoteko, zahtevek ostane odprt med obdelavo, odgovor pa prejmete celoten prepis. Ni ID-ja opravila za preverjanje stanja niti ni treba konfigurirati spletnega klica (webhook). To bistveno poenostavi vašo kodo, vendar morate za dolge datoteke določiti velik časovni okvir (timeout).
Preden začnete s kodiranjem, se prepričajte, da izpolnjujete tri predpogoje: račun na platformi Mistral (console.mistral.ai), aktivni ključ API in nameščen Python SDK.
Namestitev SDK-ja
pip install mistralai
Parametri klica
Vse poteka prek client.audio.transcriptions.complete(). Dva parametra sta obvezna, štirje pa izbirni. Prav ti izbirni parametri spremenijo surov prepis v uporaben izdelek.
Obvezni parametri
model— Identifikator modela. Za transkripcijo brez povezave uporabite"voxtral-mini-transcribe-3"(priporočeno) ali pripeto različico, kot je"voxtral-mini-transcribe-3".filealifile_url— Zvočna datoteka za transkripcijo. Na voljo imate dve možnosti:file: Slovar{"content": file_object, "file_name": "name.mp3"}za neposredno nalaganje.file_url: Javni URL, ki kaže na zvočno datoteko.
Izbira med file in file_url je arhitekturna odločitev. Če je vaš zvok že shranjen na javno dostopni lokaciji, file_url prepreči usmerjanje datoteke prek vašega strežnika. Če datoteka prihaja z uporabnikove naprave ali iz zasebnega shrambe, je neposredno nalaganje nujno.
Izbirni parametri
Štiri izbirne nastavitve spremenijo naravo izhoda.
language pričakuje kodo jezika ISO, kot sta "fr" ali "en", in obide samodejno zaznavanje. To vsilite pri homogenih serijah, na primer pri katalogu intervjujev, opravljenih izključno v francoščini, da preprečite, da bi kratek angleški odlomek sredi datoteke preklopil model. Upoštevajte, da je nezdružljiv s timestamp_granularities.
timestamp_granularities sprejme seznam ["segment"] in sproži vračanje časovnih žigov segment za segmentom. Pri Voxtral 3 granularnost word ne obstaja več in vrne napako 400. Ta parameter omogoča datoteke s podnapisi, sinhronizirane z videom, ali indeksirane odlomke v dvourni konferenci.
diarize je boolova vrednost. Ko je nastavljena na True, model identificira govorce in vsak segment pripiše enemu izmed njih. Za izvršni odbor s šestimi člani je to razlika med anonimnim zidom besedila in poročilom, kjer je vsako zavezo mogoče pripisati konkretni osebi.
Končno, context_bias sprejme seznam izrazov – posamezno besedo ali frazo s presledki, kot je ime izdelka – za izboljšanje prepoznavanja specifičnega besedišča. Število vnosov ni več fiksno, vendar si delijo kontekstno okno z zvokom, zato seznam ohranite kratek. Sestanek inženirjev z izrazi, kot sta “Kubernetes” in “GDPR”, postane s to nastavitvijo bistveno bolj berljiv.
Podprti zvočni formati
Voxtral sprejema običajne zvočne formate in redko boste morali kaj vnaprej pretvarjati. V dvomih si oglejte stran Audio formats v dokumentaciji.
| Format | Značilnost |
|---|---|
| MP3 | Najpogostejši, dobro stiskanje |
| WAV | Nestisnjeno, najvišja kakovost |
| FLAC | Brezizgubno stiskanje |
| OGG | Odprt format, dobro stiskanje |
| M4A / AAC | Appleov format, pogost na mobilnih napravah |
| WEBM | Spletni format, pogost za snemanja v brskalniku |
Kritična omejitev je kontekstno okno modela, ki si ga delita zvok in besedišče context_bias. Zahtevek, ki preseže to omejitev, bo zavrnjen z napako 400; API datoteke ne obreže. Pri zelo dolgih datotekah, kot je celodnevni seminar, jih razdelite pred pošiljanjem, po možnosti na mestih tišine, da se izognete rezanju stavkov na pol.
Struktura odgovora
Odgovor vsebuje vsaj prepisano besedilo:
response.text # Celotno prepisano besedilo (str)
Če ste zahtevali časovne žige (timestamp_granularities), odgovor vključuje tudi:
response.segments # Seznam segmentov z začetkom, koncem in besedilom
Če ste omogočili ločevanje govorcev (diarize=True), vsak segment vključuje identiteto govorca:
segment.speaker_id # Identifikator govorca (str)
segment.start # Čas začetka v sekundah (float)
segment.end # Čas konca v sekundah (float)
segment.text # Besedilo segmenta (str)
Skratka, oblika vrnjenega objekta je odvisna od vašega zahtevka. Koda, ki iterira prek response.segments, ne da bi podali timestamp_granularities, bo spodletela. Vedno preverite skladnost med vhodnimi parametri in obravnavo izhoda.
Kombinacije parametrov
Tukaj je pet veljavnih kombinacij, s katerimi se boste najpogosteje srečali, od najpreprostejše do najbolj specializirane.
# Preprosta transkripcija (samo besedilo)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Z vsiljenim jezikom (brez časovnih žigov)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# S časovnimi žigi po segmentih
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Z ločevanjem govorcev + časovnimi žigi
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# S pristranskostjo konteksta (context biasing)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Presenetljiva omejitev v Voxtral 2 je bila, da language in timestamp_granularities nista mogla biti uporabljena skupaj v istem klicu. Dokumentacija za Voxtral 3 te omejitve ne omenja več; preden se zanesete na to, to preverite s testom.
Avtentikacija
Vsi zahtevki zahtevajo veljaven ključ API, podan konstruktorju klienta. Med razvojem zadostuje neposreden argument. V produkcijskem okolju uporabite spremenljivko okolja, da preprečite, da bi ključ končal v vašem repozitoriju Git.
from mistralai.client import Mistral
# Prek neposrednega argumenta
client = Mistral(api_key="your-api-key")
# Ali prek spremenljivke okolja (priporočeno za produkcijo)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Ključne ugotovitve
- Končna točka
/audio/transcriptionsje sinhrona: pošljite datoteko, prejmite besedilo. - Dva načina nalaganja: neposredno nalaganje (
file) ali javni URL (file_url). - Izbirni parametri:
language,timestamp_granularities,diarize,context_bias. - V Voxtral 2 sta bila
languageintimestamp_granularitiesmedsebojno izključujoča; dokumentacija za Voxtral 3 tega ne navaja več. - Podprti so običajni zvočni formati; omejitev je kontekstno okno, ki si ga delita zvok in
context_bias(napaka 400, če je preseženo). - Ločevanje govorcev in časovne žige je mogoče kombinirati.