Rozhranie API pre offline prepis
Na tejto strane
Kurz aktualizovaný 3. novembra 2026 pre Voxtral 3 na základe príručky Mistral Migrate from Voxtral 2: Modely Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), ktoré boli zastarané 31. októbra 2026 a vyradené 30. apríla 2027, sú v príkladoch nahradené modelmivoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3avoxtral-mini-tts-3-0. Kľúčové zmeny: časové pečiatky sú len na úrovni segmentov (wordvráti chybu 400), je podporovaná diarizácia v reálnom čase, nastavenia relácie v reálnom čase sú uzamknuté po prvom zvukovom bloku a položkycontext_biassú voľného formátu (frázy s medzerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Koncový bod pre prepis
Offline API pre prepis od spoločnosti Mistral využíva koncový bod /audio/transcriptions. Ide o synchronné API: odošleš zvukový súbor, požiadavka zostane otvorená počas spracovania a v odpovedi dostaneš úplný prepis. Nie je potrebné žiadne ID úlohy na dotazovanie ani konfigurácia webhooku. To výrazne zjednodušuje tvoj kód, ale pri dlhých súboroch musíš nastaviť dostatočne dlhé časové limity (timeouty).
Predtým, než začneš kódovať, uisti sa, že spĺňaš tri predpoklady: účet na platforme Mistral (console.mistral.ai), aktívny API kľúč a nainštalované Python SDK.
Inštalácia SDK
pip install mistralai
Parametre volania
Všetko prebieha cez client.audio.transcriptions.complete(). Dva parametre sú povinné a štyri voliteľné. Práve tieto voliteľné parametre menia surový prepis na použiteľný výstup.
Povinné parametre
model— Identifikátor modelu. Pre offline prepis použi"voxtral-mini-transcribe-3"(odporúčané) alebo pripnutú verziu, napríklad"voxtral-mini-transcribe-3".filealebofile_url— Zvukový súbor na prepis. Máš dve možnosti:file: Slovník{"content": file_object, "file_name": "name.mp3"}pre priame nahratie.file_url: Verejná URL adresa odkazujúca na zvukový súbor.
Výber medzi file a file_url je architektonické rozhodnutie. Ak je tvoj zvuk už uložený na verejne dostupnom mieste, file_url zabráni smerovaniu súboru cez tvoj server. Ak súbor pochádza zo zariadenia používateľa alebo zo súkromného úložiska, je potrebné priame nahratie.
Voliteľné parametre
Štyri voliteľné nastavenia menia povahu výstupu.
language očakáva kód jazyka podľa normy ISO, napríklad "fr" alebo "en", a obchádza automatickú detekciu. Vynúť toto nastavenie pre homogénne dávky, ako je katalóg rozhovorov vedených výlučne vo francúzštine, aby sa zabránilo prepínaniu modelu uprostred súboru pri krátkej anglickej pasáži. Všimni si, že je nekompatibilný s timestamp_granularities.
timestamp_granularities prijíma zoznam ["segment"] a spúšťa vrátenie časových pečiatok segment po segmente. Pri Voxtral 3 granularita word už neexistuje a vráti chybu 400. Tento parameter umožňuje vytvárať titulkové súbory synchronizované s videom alebo indexované pasáže v dvojhodinovej konferencii.
diarize je boolean hodnota. Ak je nastavená na True, model identifikuje hovoriacich a priradí každý segment jednému z nich. Pre výkonný výbor so šiestimi členmi je to rozdiel medzi anonymnou stenou textu a správou, kde je každý záväzok priraditeľný konkrétnej osobe.
Nakoniec, context_bias prijíma zoznam termínov – jednotlivé slová alebo frázy s medzerami, ako je názov produktu – na zlepšenie rozpoznávania špecifickej slovnej zásoby. Počet položiek už nie je fixný, ale zdieľajú kontextové okno so zvukom, takže zoznam udržuj krátky. Inžinierske stretnutie s termínmi ako „Kubernetes“ a „GDPR“ sa s týmto nastavením stane výrazne čitateľnejším.
Podporované zvukové formáty
Voxtral akceptuje bežné zvukové formáty a zriedka budeš potrebovať niečo vopred konvertovať. Ak si nie si istý, pozri si stránku Audio formats v dokumentácii.
| Formát | Charakteristika |
|---|---|
| MP3 | Najbežnejší, dobrá kompresia |
| WAV | Nekompresný, maximálna kvalita |
| FLAC | Bezstratová kompresia |
| OGG | Otvorený formát, dobrá kompresia |
| M4A / AAC | Formát Apple, bežný na mobilných zariadeniach |
| WEBM | Webový formát, bežný pre nahrávky z prehliadača |
Kritickým limitom je kontextové okno modelu, ktoré je zdieľané medzi zvukom a slovnou zásobou context_bias. Požiadavka presahujúca tento limit bude zamietnutá s chybou 400; API súbor neoreže. Pri veľmi dlhých súboroch, ako je celodenný seminár, rozdeľ ich pred odoslaním, ideálne v miestach ticha, aby sa predišlo prerezaniu viet napoly.
Štruktúra odpovede
Odpoveď obsahuje minimálne prepísaný text:
response.text # Úplný prepísaný text (str)
Ak si vyžiadal časové pečiatky (timestamp_granularities), odpoveď obsahuje aj:
response.segments # Zoznam segmentov so začiatkom, koncom a textom
Ak si povolil diarizáciu (diarize=True), každý segment obsahuje identitu hovoriaceho:
segment.speaker_id # Identifikátor hovoriaceho (str)
segment.start # Čas začiatku v sekundách (float)
segment.end # Čas konca v sekundách (float)
segment.text # Text segmentu (str)
Stručne povedané, tvar vráteného objektu závisí od tvojej požiadavky. Kód, ktorý iteruje cez response.segments bez zadania timestamp_granularities, zlyhá. Vždy over konzistentnosť medzi vstupnými parametrami a spracovaním výstupu.
Kombinácie parametrov
Tu je päť platných kombinácií, s ktorými sa stretneš najčastejšie, od najjednoduchších po najšpecializovanejšie.
# Jednoduchý prepis (len text)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# S vynúteným jazykom (bez časových pečiatok)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# S časovými pečiatkami segmentov
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# S diarizáciou + časovými pečiatkami
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# S kontextovým zvýraznením (biasing)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Prekvapivým obmedzením vo Voxtral 2 bolo, že language a timestamp_granularities sa nemohli použiť spolu v rovnakom volaní. Dokumentácia Voxtral 3 toto obmedzenie už nespomína; over si to testom predtým, než sa na to spoľahneš.
Autentifikácia
Všetky požiadavky vyžadujú platný API kľúč odovzdaný konštruktorovi klienta. Vo vývojovom prostredí stačí priamy argument. V produkčnom prostredí použi premennú prostredia, aby sa kľúč nedostal do tvojho Git repozitára.
from mistralai.client import Mistral
# Cez priamy argument
client = Mistral(api_key="your-api-key")
# Alebo cez premennú prostredia (odporúčané pre produkciu)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Kľúčové poznatky
- Koncový bod
/audio/transcriptionsje synchronný: odošli súbor, dostaneš text. - Dva režimy nahrávania: priame nahratie (
file) alebo verejná URL (file_url). - Voliteľné parametre:
language,timestamp_granularities,diarize,context_bias. - Vo Voxtral 2 boli
languageatimestamp_granularitiesvzájomne sa vylučujúce; dokumentácia Voxtral 3 to už neuvádza. - Podporované sú bežné zvukové formáty; limitom je kontextové okno zdieľané medzi zvukom a
context_bias(pri prekročení chyba 400). - Diarizáciu a časové pečiatky možno kombinovať.