API de transkriptsiooni offline-režiimis
Sellel lehel
Kursust uuendati 3. novembril 2026 Voxtral 3 jaoks, tuginedes Mistrali juhendile Migrate from Voxtral 2: Voxtral 2 mudelid (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), mis tunnistati aegunuks 31. oktoobril 2026 ja lõpetati 30. aprillil 2027, on näidetes asendatud mudelitegavoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3javoxtral-mini-tts-3-0. Peamised muudatused: ajatemplid on ainult lõigupõhised (wordtagastab vea 400), reaalajas kõneleja eristamine on toetatud, reaalajaseansi seaded lukustuvad pärast esimest helilõiku jacontext_biaskirjed on vabas vormingus (fraasid tühikutega). Allikad: Migrate from Voxtral 2 · Speech to Text.
Transkriptsiooni lõpp-punkt
Mistrali offline-transkriptsiooni API kasutab lõpp-punkti /audio/transcriptions. See on sünkroonne API: saadad helifaili, päring jääb töötlemise ajaks avatuks ja saad vastuses kogu transkriptsiooni. Pole ülesande ID-d, mida pollida, ega veebikonksu, mida seadistada. See lihtsustab sinu koodi oluliselt, kuid pikkade failide jaoks pead lubama piisavalt pikad ajalõpid.
Enne kodeerimise alustamist veendu, et sul on kolm eeldust: Mistrali platvormi konto (console.mistral.ai), aktiivne API-võti ja paigaldatud Pythoni SDK.
SDK paigaldamine
pip install mistralai
Väljakutse parameetrid
Kõik toimub funktsiooni client.audio.transcriptions.complete() kaudu. Nõutud on kaks parameetrit ja valikulisi on neli. Just need valikulised parameetrid muudavad toore transkriptsiooni kasutatavaks tulemuseks.
Nõutud parameetrid
model— Mudeli identifikaator. Offline-transkriptsiooni jaoks kasuta"voxtral-mini-transcribe-3"(soovitatav) või fikseeritud versiooni, nagu"voxtral-mini-transcribe-3".filevõifile_url— Transkribeeritav helifail. Sul on kaks võimalust:file: Sõnastik{"content": file_object, "file_name": "name.mp3"}otseseks üleslaadimiseks.file_url: Avalik URL, mis viitab helifailile.
Valik file ja file_url vahel on arhitektuuriline otsus. Kui su heli on juba avalikus kohas salvestatud, väldib file_url faili marsruutimist läbi sinu serveri. Kui fail pärineb kasutaja seadmest või privaatsest salvestusruumist, on otsene üleslaadimine vajalik.
Valikulised parameetrid
Neli valikulist seadet muudavad väljundi olemust.
language eeldab ISO keelekoodi, näiteks "fr" või "en", ja möödub automaatsest tuvastamisest. Sunni seda ühtlaste partiide puhul, nagu näiteks kataloog intervjuudest, mis on tehtud täielikult prantsuse keeles, et vältida olukorda, kus lühike ingliskeelne lõik sunnib mudelit faili keskel keelt vahetama. Pane tähele, et see on kokkusobimatu parameetriga timestamp_granularities.
timestamp_granularities võtab vastu loendi ["segment"] ja käivitab ajatemplite tagastamise lõikude kaupa. Voxtral 3 puhul granulaarsust word enam ei eksisteeri ja see tagastab vea 400. See parameeter võimaldab luua videoga sünkroniseeritud subtiitrifaile või indekseerida lõike kahetunnisel konverentsil.
diarize on boolean-tüüpi. Kui see on määratud väärtusele True, tuvastab mudel kõnelejad ja omistab igale lõigule ühe neist. Kuueliikmelise juhatuse koosoleku puhul teeb see erinevuse anonüümse tekstiseina ja aruande vahel, kus iga kohustus on omistatav.
Lõpuks aktsepteerib context_bias terminite loendit – üks sõna või fraas tühikutega, nagu toote nimi –, et parandada spetsiifilise sõnavara tuvastamist. Kirjete arv ei ole enam fikseeritud, kuid need jagavad kontekstiakent heliga, seega hoia loend lühike. Insenerikoosolek, kus esinevad terminid nagu “Kubernetes” ja “GDPR”, muutub selle seadega oluliselt loetavamaks.
Toetatud helivormingud
Voxtral aktsepteerib levinud helivorminguid ja sul on harva vaja midagi eelnevalt konverteerida. Kahtluse korral vaata dokumentatsiooni lehte Audio formats.
| Vorming | Omadus |
|---|---|
| MP3 | Kõige levinum, hea tihendus |
| WAV | Tihendamata, maksimaalne kvaliteet |
| FLAC | Kadudeta tihendus |
| OGG | Avatud vorming, hea tihendus |
| M4A / AAC | Apple’i vorming, levinud mobiilseadmetes |
| WEBM | Veebivorming, levinud brauserisalvestiste puhul |
Kriitiline piirang on mudeli kontekstiaken, mida jagavad heli ja context_bias sõnavara. Sellest piirangust suurem päring lükatakse tagasi veaga 400; API ei lühenda faili. Väga pikkade failide, nagu päevane seminar, puhul jaga need enne saatmist, eelistatavalt vaikusekohtades, et vältida lausete poolitamist.
Vastuse struktuur
Vastus sisaldab vähemalt transkribeeritud teksti:
response.text # Kogu transkribeeritud tekst (str)
Kui küsisid ajatempleid (timestamp_granularities), sisaldab vastus ka:
response.segments # Lõikude loend algusaja, lõpuaja ja tekstiga
Kui lubasid kõneleja eristamise (diarize=True), sisaldab iga lõik kõneleja identiteeti:
segment.speaker_id # Kõneleja identifikaator (str)
segment.start # Algusaeg sekundites (float)
segment.end # Lõpuaeg sekundites (float)
segment.text # Lõigu tekst (str)
Lühidalt öeldes sõltub tagastatud objekti kuju sinu päringust. Kood, mis iteratsioonib üle response.segments ilma timestamp_granularities parameetrit kasutamata, ebaõnnestub. Kontrolli alati sisendparameetrite ja väljundi töötlemise kooskõla.
Parameetrite kombinatsioonid
Siin on viis kehtivat kombinatsiooni, mida kohtad kõige sagedamini, lihtsaimast kõige spetsiifilisemani.
# Lihtne transkriptsioon (ainult tekst)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Sunnitud keelega (ajatemplid puuduvad)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Lõigu ajatemplitega
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Kõneleja eristamine + ajatemplid
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Konteksti kallutamisega
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Üllatav piirang Voxtral 2-s oli see, et language ja timestamp_granularities ei saanud samas väljakutses koos kasutada. Voxtral 3 dokumentatsioon seda piirangut enam ei maini; enne sellele tuginemist kontrolli seda testiga.
Autentimine
Kõik päringud nõuavad kehtivat API-võtit, mis antakse kliendi konstruktorile. Arenduskeskkonnas piisab otsesest argumendist. Tootmiskeskkonnas kasuta keskkonnamuutujat, et vältida võtme sattumist sinu Git-i hoidlasse.
from mistralai.client import Mistral
# Otsese argumendina
client = Mistral(api_key="your-api-key")
# Või keskkonnamuutuja kaudu (soovitatav tootmiskeskkonnale)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Peamised punktid
- Lõpp-punkt
/audio/transcriptionson sünkroonne: saada fail, saada tekst. - Kaks üleslaadimisrežiimi: otsene üleslaadimine (
file) või avalik URL (file_url). - Valikulised parameetrid:
language,timestamp_granularities,diarize,context_bias. - Voxtral 2-s olid
languagejatimestamp_granularitiesvastastikku välistavad; Voxtral 3 dokumentatsioon seda enam ei väida. - Toetatud on levinud helivormingud; piiranguks on kontekstiaken, mida jagavad heli ja
context_bias(ületamisel tekib viga 400). - Kõneleja eristamist ja ajatempleid saab kombineerida.