Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-API ta' Traskrizzjoni Offline

Lezzjoni 4 / 16 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-endpoint tat-traskrizzjoni
  2. Parametri tas-sejħa
  3. Formati tal-awdjo appoġġjati
  4. Struttura tar-rispons
  5. Kombinazzjonijiet ta’ parametri
  6. Awtentikazzjoni
  7. Punti Ewlenin

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 minn voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3, u voxtral-mini-tts-3-0. Bidliet ewlenin: it-timstamps huma biss għas-segmenti (word jirritorna ż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_bias huma 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".
  • file jew file_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.

FormatKaratteristika
MP3L-aktar komuni, kompressjoni tajba
WAVMhux ikkompressat, kwalità massima
FLACKompressjoni mingħajr telf (lossless)
OGGFormat miftuħ, kompressjoni tajba
M4A / AACFormat ta’ Apple, komuni fuq mobbli
WEBMFormat 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/transcriptions huwa 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, language u timestamp_granularities kienu 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.