Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

API pro offline přepis

Lekce 4 z 16 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Koncový bod pro přepis
  2. Parametry volání
  3. Podporované zvukové formáty
  4. Struktura odpovědi
  5. Kombinace parametrů
  6. Autentizace
  7. Klíčové poznatky

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 modely voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 a voxtral-mini-tts-3-0. Klíčové změny: časová razítka jsou pouze po sekcích (word vrací 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žky context_bias jsou 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".
  • file nebo file_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átCharakteristika
MP3Nejběžnější, dobrá komprese
WAVNekompresní, maximální kvalita
FLACBezztrátová komprese
OGGOtevřený formát, dobrá komprese
M4A / AACFormát Apple, běžný na mobilech
WEBMWebový 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/transcriptions je 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 language a timestamp_granularities vzá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.