Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

API za transkripcijo brez povezave

Lekcija 4 od 16 Posodobljeno 3. november 2026 Razvijalec
Na tej strani
  1. Končna točka za transkripcijo
  2. Parametri klica
  3. Podprti zvočni formati
  4. Struktura odgovora
  5. Kombinacije parametrov
  6. Avtentikacija
  7. Ključne ugotovitve

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 z voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 in voxtral-mini-tts-3-0. Ključne spremembe: časovni žigi so samo po segmentih (word vrne napako 400), podprta je ločevanje govorcev v realnem času, nastavitve seje v realnem času so zaklenjene po prvem zvočnem delčku, vnosi context_bias pa 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".
  • file ali file_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.

FormatZnačilnost
MP3Najpogostejši, dobro stiskanje
WAVNestisnjeno, najvišja kakovost
FLACBrezizgubno stiskanje
OGGOdprt format, dobro stiskanje
M4A / AACAppleov format, pogost na mobilnih napravah
WEBMSpletni 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/transcriptions je 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 language in timestamp_granularities medsebojno 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.