L-API ta' Traskrizzjoni Offline
F'din il-paġna
Kors aġġornat fit-3 ta’ Novembru 2026 għal Voxtral 3, ibbażat fuq il-gwida Migrate from Voxtral 2 ta’ Mistral: Il-mudelli ta’ Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, iddeprekati fil-31 ta’ Ottubru 2026 u rtirati fit-30 ta’ April 2027, huma sostitwiti fl-eżempji minnvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3, uvoxtral-mini-tts-3-0. Bidliet ewlenin: it-timstamps huma biss għas-segmenti (wordjirritorna żball 400), id-djarizzazzjoni f’ħin reali hija appoġġjata, is-settings tas-sessjoni f’ħin reali jingħalqu wara l-ewwel biċċa awdjo, u l-entrati ta’context_biashuma f’forma libera (frażijiet b’spazji). Sorsi: Migrate from Voxtral 2 · Speech to Text.
L-endpoint tat-traskrizzjoni
L-API ta’ traskrizzjoni offline ta’ Mistral tuża l-endpoint /audio/transcriptions. Din hija API sinkrona: tibgħat fajl awdjo, it-talba tibqa’ miftuħa matul l-ipproċessar, u tirċievi t-traskrizzjoni sħiħa fir-rispons. M’hemm l-ebda ID ta’ kompitu (task ID) li trid tinterroga u l-ebda webhook li trid tikkonfigura. Dan jissimplifika l-kodiċi tiegħek b’mod sinifikanti, iżda trid tippermetti timeouts ġenerużi għal fajls twal.
Qabel ma tibda tikteb il-kodiċi, żgur li għandek tliet prerekwiżiti: kont tal-pjattaforma Mistral (console.mistral.ai), API key attiva, u l-SDK tal-Python installat.
Installazzjoni tal-SDK
pip install mistralai
Parametri tas-sejħa
Kollox jgħaddi minn client.audio.transcriptions.complete(). Żewġ parametri huma meħtieġa, u erbgħa huma fakultattivi. Dawn il-parametri fakultattivi huma dak li jibdlu traskrizzjoni mhux maħduma f’dokumentazzjoni utilizzabbli.
Parametri meħtieġa
model— L-identifikatur tal-mudell. Għat-traskrizzjoni offline, uża"voxtral-mini-transcribe-3"(rakkomandat) jew verżjoni ffissata bħal"voxtral-mini-transcribe-3".filejewfile_url— Il-fajl awdjo li trid ttraskrivi. Għandek żewġ għażliet:file: Dizzjunarju{"content": file_object, "file_name": "name.mp3"}għat-tlugħ dirett.file_url: URL pubbliku li jipponta lejn il-fajl awdjo.
L-għażla bejn file u file_url hija deċiżjoni arkitettonika. Jekk l-awdjo tiegħek diġà maħżun f’post aċċessibbli pubblikament, file_url jevita li tgħaddi l-fajl mis-server tiegħek. Jekk il-fajl jiġi minn apparat tal-utent jew ħażna privata, it-tlugħ dirett huwa meħtieġ.
Parametri fakultattivi
Erba’ settings fakultattivi jbiddlu n-natura tal-output.
language jistenna kodiċi tal-lingwa ISO, bħal "fr" jew "en", u jaqbeż id-detezzjoni awtomatika. Furza dan għal lottijiet omoġenji, bħal katalogu ta’ intervisti mwettqa kompletament bil-Franċiż, biex tevita li biċċa qasira bl-Ingliż tbiddel il-mudell f’nofs il-fajl. Innota li dan huwa inkompatibbli ma’ timestamp_granularities.
timestamp_granularities jieħu l-lista ["segment"] u jattiva r-ritorn ta’ timestamps segment b’segment. Ma’ Voxtral 3, il-granularità word ma teżistix aktar u tirritorna żball 400. Dan il-parametri jippermetti fajls tas-sottotitoli sinkronizzati mal-vidjo jew passi indiċjati f’konferenza ta’ sagħtejn.
diarize huwa boolean. Meta ssettjat għal True, il-mudell jidentifika l-kelliema u jattribwixxi kull segment lil wieħed minnhom. Għal kumitat eżekuttiv ta’ sitt persuni, din hija d-differenza bejn ħajt anonimu ta’ test u rapport fejn kull impenn huwa attribwibbli.
Fl-aħħar nett, context_bias jaċċetta lista ta’ termini — kelma waħda jew frażi b’spazji, bħal isem ta’ prodott — biex itejjeb ir-rikonoxximent ta’ vokabolarju speċifiku. In-numru ta’ entrati m’għadux iffissat, iżda jaqsmu t-tieqa tal-kuntest (context window) mal-awdjo, allura żomm il-lista qasira. Laqgħa tal-inġinerija li fiha termini bħal “Kubernetes” u “GDPR” issir ferm aktar leġibbli b’dan is-setting.
Formati tal-awdjo appoġġjati
Voxtral jaċċetta formati tal-awdjo komuni, u rari se jkollok bżonn tikkonverti xi ħaġa minn qabel. Jekk ikollok dubju, irreferi għall-paġna Audio formats fid-dokumentazzjoni.
| Format | Karatteristika |
|---|---|
| MP3 | L-aktar komuni, kompressjoni tajba |
| WAV | Mhux ikkompressat, kwalità massima |
| FLAC | Kompressjoni mingħajr telf (lossless) |
| OGG | Format miftuħ, kompressjoni tajba |
| M4A / AAC | Format ta’ Apple, komuni fuq mobbli |
| WEBM | Format tal-web, komuni għal reġistrazzjonijiet tal-browser |
Il-limitu kritiku huwa t-tieqa tal-kuntest (context window) tal-mudell, li hija maqsuma bejn l-awdjo u l-vokabolarju ta’ context_bias. Talba li taqbeż dan il-limiti tiġi miċħuda b’żball 400; l-API ma taqta’x il-fajl. Għal fajls twal ħafna, bħal seminar ta’ ġurnata sħiħa, aqsmhom qabel ma tibgħathom, preferibbilment f’punti ta’ silenzju biex tevita li taqta’ sentenzi f’nofsuhom.
Struttura tar-rispons
Ir-rispons jikkontjeni mill-inqas it-test traskritt:
response.text # It-test traskritt sħiħ (str)
Jekk talbejt it-timstamps (timestamp_granularities), ir-rispons jinkludi wkoll:
response.segments # Lista ta' segmenti b'bidu, tmiem, test
Jekk ippermettejt id-djarizzazzjoni (diarize=True), kull segment jinkludi l-identità tal-kelliem:
segment.speaker_id # Identifikatur tal-kelliem (str)
segment.start # Ħin tal-bidu f'sekondi (float)
segment.end # Ħin tat-tmiem f'sekondi (float)
segment.text # Test tas-segment (str)
Fil-qosor, il-forma tal-oġġett irritornat tiddependi mit-talba tiegħek. Kodiċi li jgħaddi minn response.segments mingħajr ma tgħaddi timestamp_granularities se jfalli. Iċċekkja dejjem il-konsistenza bejn il-parametri tal-input tiegħek u l-immaniġġjar tal-output tiegħek.
Kombinazzjonijiet ta’ parametri
Hawn huma l-ħames kombinazzjonijiet validi li se tiltaqa’ magħhom l-aktar spiss, mill-aktar sempliċi għall-aktar speċjalizzati.
# Traskrizzjoni sempliċi (test biss)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Bil-lingwa furzata (l-ebda timestamp)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# B'timstamps tas-segmenti
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Bid-djarizzazzjoni + timstamps
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Bil-bias tal-kuntest (context biasing)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Vinċolu sorprendenti f’Voxtral 2 kien li language u timestamp_granularities ma setgħux jintużaw flimkien fl-istess sejħa. Id-dokumentazzjoni ta’ Voxtral 3 ma ssemmix aktar din ir-restrizzjoni; ivverifika dan b’test qabel ma tiddependi fuqu.
Awtentikazzjoni
It-talbiet kollha jeħtieġu API key valida mgħoddija lill-kostruttur tal-klijent. Fl-iżvilupp, argument dirett huwa biżżejjed. Fil-produzzjoni, uża varjabbli tal-ambjent biex tevita li l-key tispiġġa fir-repożitorju Git tiegħek.
from mistralai.client import Mistral
# Permezz ta' argument dirett
client = Mistral(api_key="your-api-key")
# Jew permezz ta' varjabbli tal-ambjent (rakkomandat għall-produzzjoni)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Punti Ewlenin
- L-endpoint
/audio/transcriptionshuwa sinkronu: ibgħat il-fajl, irċievi t-test. - Żewġ modi ta’ tlugħ: tlugħ dirett (
file) jew URL pubbliku (file_url). - Parametri fakultattivi:
language,timestamp_granularities,diarize,context_bias. - F’Voxtral 2,
languageutimestamp_granularitieskienu esklużivi reċiprokament; id-dokumentazzjoni ta’ Voxtral 3 ma tgħidx aktar hekk. - Il-formati tal-awdjo komuni huma appoġġjati; il-limitu huwa t-tieqa tal-kuntest maqsuma bejn l-awdjo u
context_bias(żball 400 jekk jinqabeż). - Id-djarizzazzjoni u t-timstamps jistgħu jiġu kkombinati.