Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Rozhranie API pre offline prepis

Lekcia 4 z 16 Aktualizované 3. novembra 2026 Vývojár
Na tejto strane
  1. Koncový bod pre prepis
  2. Parametre volania
  3. Podporované zvukové formáty
  4. Štruktúra odpovede
  5. Kombinácie parametrov
  6. Autentifikácia
  7. Kľúčové poznatky

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é modelmi voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 a voxtral-mini-tts-3-0. Kľúčové zmeny: časové pečiatky sú len na úrovni segmentov (word vrá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žky context_bias sú 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".
  • file alebo file_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átCharakteristika
MP3Najbežnejší, dobrá kompresia
WAVNekompresný, maximálna kvalita
FLACBezstratová kompresia
OGGOtvorený formát, dobrá kompresia
M4A / AACFormát Apple, bežný na mobilných zariadeniach
WEBMWebový 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/transcriptions je 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 language a timestamp_granularities vzá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ť.