Salt la conținutul principal
Română— Alege o limbă
Meniu

API-ul de transcriere offline

Lecția 4 din 16 Actualizată 3 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Punctul final de transcriere
  2. Parametrii apelului
  3. Formate audio suportate
  4. Structura răspunsului
  5. Combinații de parametri
  6. Autentificare
  7. Puncte cheie

Curs actualizat la 3 noiembrie 2026 pentru Voxtral 3, pe baza ghidului Migrate from Voxtral 2 de la Mistral: modelele Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), depreciate la 31 octombrie 2026 și retrase la 30 aprilie 2027, sunt înlocuite în exemple prin voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 și voxtral-mini-tts-3-0. Modificări cheie: marcajele temporale sunt doar pe segmente (word returnează o eroare 400), diarizarea în timp real este suportată, setările sesiunii în timp real sunt blocate după primul fragment audio, iar intrările context_bias sunt în formă liberă (fraze cu spații). Surse: Migrate from Voxtral 2 · Speech to Text.

Punctul final de transcriere

API-ul de transcriere offline de la Mistral utilizează punctul final /audio/transcriptions. Este un API sincron: trimiteți un fișier audio, cererea rămâne deschisă în timpul procesării și primiți transcrierea completă în răspuns. Nu există un ID de sarcină de interogat și niciun webhook de configurat. Acest lucru vă simplifică semnificativ codul, dar trebuie să alocați timeout-uri generoase pentru fișierele lungi.

Înainte de a începe codarea, asigurați-vă că aveți trei prerechizite: un cont de platformă Mistral (console.mistral.ai), o cheie API activă și SDK-ul Python instalat.

Instalarea SDK-ului

pip install mistralai

Parametrii apelului

Totul trece prin client.audio.transcriptions.complete(). Doi parametri sunt obligatorii, iar patru sunt opționali. Acești parametri opționali sunt cei care transformă o transcriere brută într-un livrabil utilizabil.

Parametri obligatorii

  • model — Identificatorul modelului. Pentru transcrierea offline, utilizați "voxtral-mini-transcribe-3" (recomandat) sau o versiune fixată precum "voxtral-mini-transcribe-3".
  • file sau file_url — Fișierul audio de transcris. Aveți două opțiuni:
    • file: Un dicționar {"content": file_object, "file_name": "name.mp3"} pentru încărcare directă.
    • file_url: Un URL public care indică spre fișierul audio.

Alegerea între file și file_url este o decizie de arhitectură. Dacă audio-ul dumneavoastră este deja stocat într-o locație accesibilă public, file_url evită rutarea fișierului prin serverul dumneavoastră. Dacă fișierul provine de pe dispozitivul unui utilizator sau dintr-o stocare privată, încărcarea directă este necesară.

Parametri opționali

Patru setări opționale modifică natura ieșirii.

language așteaptă un cod de limbă ISO, cum ar fi "fr" sau "en", și ocolește detectarea automată. Impuneți acest lucru pentru loturi omogene, cum ar fi un catalog de interviuri desfășurate integral în franceză, pentru a preveni ca un scurt pasaj în engleză să comute modelul la mijlocul fișierului. Rețineți că este incompatibil cu timestamp_granularities.

timestamp_granularities primește lista ["segment"] și declanșează returnarea marcajelor temporale segment cu segment. Odată cu Voxtral 3, granularitatea word nu mai există și returnează o eroare 400. Acest parametru permite fișiere de subtitrare sincronizate cu video sau pasaje indexate într-o conferință de două ore.

diarize este un boolean. Când este setat la True, modelul identifică vorbitorii și atribuie fiecare segment unuia dintre ei. Pentru un comitet executiv de șase persoane, aceasta este diferența dintre un zid anonim de text și un raport în care fiecare angajament este atribuit.

În final, context_bias acceptă o listă de termeni—un singur cuvânt sau o frază cu spații, cum ar fi un nume de produs—pentru a îmbunătăți recunoașterea unui vocabular specific. Numărul de intrări nu mai este fix, dar acestea partajează fereastra de context cu audio-ul, așa că mențineți lista scurtă. O întâlnire de inginerie care include termeni precum “Kubernetes” și “GDPR” devine semnificativ mai lizibilă cu această setare.

Formate audio suportate

Voxtral acceptă formate audio comune și rareori veți avea nevoie să convertiți ceva în prealabil. În caz de dubiu, consultați pagina Audio formats din documentație.

FormatCaracteristică
MP3Cel mai comun, compresie bună
WAVNecompresat, calitate maximă
FLACCompresie fără pierderi
OGGFormat deschis, compresie bună
M4A / AACFormat Apple, comun pe mobil
WEBMFormat web, comun pentru înregistrări din browser

Limita critică este fereastra de context a modelului, care este partajată între audio și vocabularul context_bias. O cerere care depășește această limită este respinsă cu o eroare 400; API-ul nu trunchiază fișierul. Pentru fișiere foarte lungi, cum ar fi un seminar de o zi întreagă, divizați-le înainte de trimitere, de preferință în punctele de liniște, pentru a evita tăierea propozițiilor la jumătate.

Structura răspunsului

Răspunsul conține cel puțin textul transcris:

response.text          # Textul complet transcris (str)

Dacă ați solicitat marcaje temporale (timestamp_granularities), răspunsul include, de asemenea:

response.segments      # Listă de segmente cu start, end, text

Dacă ați activat diarizarea (diarize=True), fiecare segment include identitatea vorbitorului:

segment.speaker_id        # Identificatorul vorbitorului (str)
segment.start          # Timpul de început în secunde (float)
segment.end            # Timpul de sfârșit în secunde (float)
segment.text           # Textul segmentului (str)

Pe scurt, forma obiectului returnat depinde de cererea dumneavoastră. Codul care iterează peste response.segments fără a trece timestamp_granularities va eșua. Verificați întotdeauna consistența dintre parametrii de intrare și gestionarea ieșirii.

Combinații de parametri

Iată cele cinci combinații valide pe care le veți întâlni cel mai des, de la cea mai simplă la cea mai specializată.

# Transcriere simplă (doar text)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"}
)

# Cu limbă forțată (fără marcaje temporale)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Cu marcaje temporale pe segmente
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Cu diarizare + marcaje temporale
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Cu bias de context
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/audio.mp3",
    context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)

O constrângere surprinzătoare în Voxtral 2 era că language și timestamp_granularities nu puteau fi utilizate împreună în același apel. Documentația Voxtral 3 nu mai menționează această restricție; verificați acest lucru printr-un test înainte de a vă baza pe el.

Autentificare

Toate cererile necesită o cheie API validă transmisă constructorului clientului. În dezvoltare, un argument direct este suficient. În producție, utilizați o variabilă de mediu pentru a preveni ca cheia să ajungă în repository-ul dumneavoastră Git.

from mistralai.client import Mistral

# Prin argument direct
client = Mistral(api_key="your-api-key")

# Sau prin variabilă de mediu (recomandat pentru producție)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Puncte cheie

  • Punctul final /audio/transcriptions este sincron: trimiteți fișierul, primiți textul.
  • Două moduri de încărcare: încărcare directă (file) sau URL public (file_url).
  • Parametri opționali: language, timestamp_granularities, diarize, context_bias.
  • În Voxtral 2, language și timestamp_granularities erau reciproc exclusive; documentația Voxtral 3 nu mai afirmă acest lucru.
  • Formatele audio comune sunt suportate; limita este fereastra de context partajată între audio și context_bias (eroare 400 dacă este depășită).
  • Diarizarea și marcajele temporale pot fi combinate.