API pro offline přepis
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 vyřazené 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 po sekcích (wordvrací chybu 400), je podporována diarizace v reálném čase, nastavení relace v reálném čase jsou uzamčena po prvním zvukovém úseku a položkycontext_biasjsou volného formátu (fráze s mezerami). Zdroje: Migrate from Voxtral 2 · Speech to Text.
Koncový bod pro přepis
Offline API pro přepis od Mistralu využívá koncový bod /audio/transcriptions. Jedná se o synchronní API: odešleš zvukový soubor, požadavek zůstává otevřený během zpracování a v odpovědi obdržíš kompletní přepis. Není zde žádné ID úlohy k dotazování ani webhook ke konfiguraci. To tvůj kód výrazně zjednodušuje, ale u dlouhých souborů musíš nastavit dostatečně dlouhé časové limity (timeouty).
Než začneš kódovat, ujisti se, že splňuješ tři předpoklady: účet na platformě Mistral (console.mistral.ai), aktivní API klíč a nainstalované Python SDK.
Instalace SDK
pip install mistralai
Parametry volání
Vše probíhá prostřednictvím client.audio.transcriptions.complete(). Dva parametry jsou povinné a čtyři volitelné. Právě tyto volitelné parametry mění surový přepis v použitelný výstup.
Povinné parametry
model— Identifikátor modelu. Pro offline přepis použij"voxtral-mini-transcribe-3"(doporučeno) nebo připnutou verzi, jako je"voxtral-mini-transcribe-3".filenebofile_url— Zvukový soubor k přepisu. Máš dvě možnosti:file: Slovník{"content": file_object, "file_name": "name.mp3"}pro přímé nahrání.file_url: Veřejná URL adresa odkazující na zvukový soubor.
Volba mezi file a file_url je architektonické rozhodnutí. Pokud je tvůj zvuk již uložen na veřejně přístupném místě, file_url se vyhne tomu, aby soubor procházel přes tvůj server. Pokud soubor pochází ze zařízení uživatele nebo z privátního úložiště, je nutné přímé nahrání.
Volitelné parametry
Čtyři volitelná nastavení mění povahu výstupu.
language očekává kód jazyka ve formátu ISO, například "fr" nebo "en", a obchází automatickou detekci. Vynuť toto nastavení u homogenních dávek, jako je katalog rozhovorů vedených výhradně ve francouzštině, aby krátký úsek v angličtině nepřepnul model uprostřed souboru. Všimni si, že je nekompatibilní s timestamp_granularities.
timestamp_granularities přijímá seznam ["segment"] a spouští vracení časových razítek po sekcích. U Voxtral 3 granularita word již neexistuje a vrací chybu 400. Tento parametr umožňuje vytvářet titulky synchronizované s videem nebo indexované pasáže ve dvouhodinové konferenci.
diarize je boolean. Pokud je nastaven na True, model identifikuje mluvčí a přiřadí každou sekci jednomu z nich. U výkonného výboru o šesti členech to znamená rozdíl mezi anonymní stěnou textu a zprávou, kde je každý závazek přiřaditelný konkrétní osobě.
Nakonec context_bias přijímá seznam termínů – jednotlivé slovo nebo frázi s mezerami, jako je název produktu – pro zlepšení rozpoznávání specifické slovní zásoby. Počet položek již není pevně stanoven, ale sdílejí kontextové okno se zvukem, takže seznam udržuj stručný. Inženýrská schůzka s termíny jako “Kubernetes” a “GDPR” se díky tomuto nastavení stane výrazně čitelnější.
Podporované zvukové formáty
Voxtral přijímá běžné zvukové formáty a jen zřídka budeš muset něco předem konvertovat. V případě pochybností se obrať na stránku Audio formats v dokumentaci.
| Formát | Charakteristika |
|---|---|
| MP3 | Nejběžnější, dobrá komprese |
| WAV | Nekompresní, maximální kvalita |
| FLAC | Bezztrátová komprese |
| OGG | Otevřený formát, dobrá komprese |
| M4A / AAC | Formát Apple, běžný na mobilech |
| WEBM | Webový formát, běžný pro nahrávky z prohlížeče |
Kritickým limitem je kontextové okno modelu, které je sdíleno mezi zvukem a slovní zásobou context_bias. Požadavek překračující tento limit je zamítnut s chybou 400; API soubor nezkrátí. U velmi dlouhých souborů, jako je celodenní seminář, je rozděl před odesláním, nejlépe v místech ticha, aby nedošlo k přerušení vět.
Struktura odpovědi
Odpověď obsahuje minimálně přepsaný text:
response.text # Celý přepsaný text (str)
Pokud jsi požadoval časová razítka (timestamp_granularities), odpověď obsahuje také:
response.segments # Seznam sekcí s start, end, text
Pokud jsi povolil diarizaci (diarize=True), každá sekce zahrnuje identitu mluvčího:
segment.speaker_id # Identifikátor mluvčího (str)
segment.start # Čas začátku v sekundách (float)
segment.end # Čas konce v sekundách (float)
segment.text # Text sekce (str)
Stručně řečeno, tvar vráceného objektu závisí na tvém požadavku. Kód, který iteruje přes response.segments bez předání timestamp_granularities, selže. Vždy ověř konzistenci mezi vstupními parametry a zpracováním výstupu.
Kombinace parametrů
Zde je pět platných kombinací, se kterými se budeš nejčastěji setkávat, od nejjednodušších po nejspecializovanější.
# Jednoduchý přepis (pouze text)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# S vynuceným jazykem (bez časových razítek)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# S časovými razítky po sekcích
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# S diarizací + časovými razítky
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ýrazněním (context biasing)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Překvapivým omezením ve Voxtral 2 bylo, že language a timestamp_granularities nemohly být použity společně v jednom volání. Dokumentace Voxtral 3 toto omezení již nezmiňuje; před spoléháním na to si to ověř testem.
Autentizace
Všechny požadavky vyžadují platný API klíč předaný konstruktoru klienta. Ve vývojovém prostředí stačí přímý argument. V produkci použij proměnnou prostředí, aby se klíč nedostal do tvého Git repozitáře.
from mistralai.client import Mistral
# Přímým argumentem
client = Mistral(api_key="your-api-key")
# Nebo přes proměnnou prostředí (doporučeno pro produkci)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Klíčové poznatky
- Koncový bod
/audio/transcriptionsje synchronní: odešli soubor, obdrž text. - Dva režimy nahrávání: přímé nahrání (
file) nebo veřejná URL (file_url). - Volitelné parametry:
language,timestamp_granularities,diarize,context_bias. - Ve Voxtral 2 byly
languageatimestamp_granularitiesvzájemně se vylučující; dokumentace Voxtral 3 toto již neuvádí. - Podporovány jsou běžné zvukové formáty; limitem je kontextové okno sdílené mezi zvukem a
context_bias(při překročení chyba 400). - Diarizaci a časová razítka lze kombinovat.