Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Az offline átírási API

4. lecke 16 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Az átírási végpont
  2. Hívási paraméterek
  3. Támogatott hangformátumok
  4. Válaszstruktúra
  5. Paraméterkombinációk
  6. Hitelesítés
  7. Főbb megállapítások

A tanfolyam frissítve: 2026. november 3., Voxtral 3 verzió, a Mistral Migrate from Voxtral 2 útmutatója alapján: a 2026. október 31-én elavult és 2027. április 30-án kivont Voxtral 2 modellek (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603) helyét a példákban a voxtral-mini-transcribe-3, a voxtral-mini-transcribe-realtime-3 és a voxtral-mini-tts-3-0 veszi át. Főbb változások: az időbélyegek csak szegmens szinten érhetők el (a word paraméter 400-as hibát ad vissza), támogatott a valós idejű beszélőazonosítás, a valós idejű munkamenet beállításai az első hangcsomag után rögzülnek, a context_bias bejegyzései pedig szabad formátumúak (szóközöket tartalmazó kifejezések is). Források: Migrate from Voxtral 2 · Speech to Text.

Az átírási végpont

A Mistral offline átírási API-ja a /audio/transcriptions végpontot használja. Ez egy szinkron API: elküldöd a hangfájlt, a kérés a feldolgozás alatt nyitva marad, és a válaszban megkapod a teljes átírást. Nincs feladatazonosító (task ID), amit lekérdeznél, és nincs konfigurálandó webhook. Ez jelentősen leegyszerűsíti a kódodat, de hosszú fájlok esetén generous timeoutokat kell engedélyezned.

Mielőtt kódolni kezdenél, győződj meg arról, hogy megvan a három előfeltétel: egy Mistral platformfiók (console.mistral.ai), egy aktív API-kulcs és a Python SDK telepítve.

Az SDK telepítése

pip install mistralai

Hívási paraméterek

Minden a client.audio.transcriptions.complete() metóduson keresztül történik. Két paraméter kötelező, négy pedig opcionális. Ezek az opcionális paraméterek változtatják meg a nyers átírást használható deliverable-lé.

Kötelező paraméterek

  • model — A modell azonosítója. Offline átíráshoz használd a "voxtral-mini-transcribe-3" (ajánlott) vagy egy rögzített verziót, mint például a "voxtral-mini-transcribe-3".
  • file vagy file_url — Az átírandó hangfájl. Két lehetőséged van:
    • file: Egy szótár {"content": file_object, "file_name": "name.mp3"} közvetlen feltöltéshez.
    • file_url: Egy nyilvános URL, amely a hangfájlra mutat.

A file és a file_url közötti választás architektúrális döntés. Ha a hanganyagod már egy nyilvánosan elérhető helyen tárolódik, a file_url elkerüli, hogy a fájlt átvezesd a szervereden. Ha a fájl egy felhasználó eszközéről vagy privát tárhelyről származik, a közvetlen feltöltés szükséges.

Opcionális paraméterek

Négy opcionális beállítás módosítja a kimenet jellegét.

A language egy ISO nyelvi kódot vár, például "fr" vagy "en", és megkerüli az automatikus nyelvfelismerést. Kényszerítsd ki ezt homogén kötegeknél, például egy kizárólag francia nyelven készült interjúkatalógus esetén, hogy megakadályozd, hogy egy rövid angol szakasz félúton nyelvváltásra késztessen modellt. Vegye figyelembe, hogy ez összeférhetetlen a timestamp_granularities paraméterrel.

A timestamp_granularities a ["segment"] listát fogadja el, és szegmensenkénti időbélyegek visszaadását váltja ki. A Voxtral 3-mal a word granularitás már nem létezik, és 400-as hibát eredményez. Ez a paraméter lehetővé teszi a videóhoz szinkronizált feliratfájlok vagy egy kétórás konferencia indexelt szakaszainak létrehozását.

A diarize egy boolean érték. Ha True-ra állítod, a modell azonosítja a beszélőket, és minden szegmenst hozzárendel egyikükhöz. Egy hatfős ügyvezető bizottság esetében ez a különbség egy névtelen szövegfal és egy olyan jegyzőkönyv között, ahol minden elköteleződés hozzárendelhető.

Végül a context_bias kifejezések listáját fogadja el – egyetlen szó vagy szóközöket tartalmazó kifejezés, például egy terméknév –, hogy javítsa a specifikus szókészlet felismerését. A bejegyzések száma már nincs rögzítve, de megosztják a kontextusablakot a hanganyaggal, ezért tartsd röviden a listát. Egy olyan mérnöki értekezlet, amelyen olyan kifejezések hangzanak el, mint a „Kubernetes“ és a „GDPR“, ezzel a beállítással jelentősen olvashatóbbá válik.

Támogatott hangformátumok

A Voxtral elfogadja a gyakori hangformátumokat, és ritkán lesz szükséged előzetes konverzióra. Ha bizonytalan vagy, tekintsd meg az Audio formats oldalt a dokumentációban.

FormátumJellemző
MP3Leggyakoribb, jó tömörítés
WAVTömörítetlen, maximális minőség
FLACVeszteségmentes tömörítés
OGGNyílt formátum, jó tömörítés
M4A / AACApple formátum, mobilon gyakori
WEBMWebes formátum, böngészős felvételeknél gyakori

A kritikus korlát a modell kontextusablaka, amely megoszlik a hanganyag és a context_bias szókészlet között. A limitet túllépő kérést a rendszer 400-as hibával utasítja el; az API nem vágja le a fájlt. Nagyon hosszú fájlok, például egy egész napos szeminárium esetén érdemes őket elküldés előtt felosztani, lehetőleg csendes pontoknál, hogy elkerüld a mondatok félbevágását.

Válaszstruktúra

A válasz legalább az átírt szöveget tartalmazza:

response.text          # A teljes átírt szöveg (str)

Ha időbélyegeket kértél (timestamp_granularities), a válasz tartalmazza még:

response.segments      # Szegmensek listája kezdettel, véggel és szöveggel

Ha engedélyezted a beszélőazonosítást (diarize=True), minden szegmens tartalmazza a beszélő azonosságát:

segment.speaker_id        # Beszélő azonosítója (str)
segment.start          # Kezdési idő másodpercben (float)
segment.end            # Befejezési idő másodpercben (float)
segment.text           # Szegmens szövege (str)

Röviden: a visszaadott objektum alakja a kérésedtől függ. Az a kód, amely a response.segments elemein iterál anélkül, hogy átadná a timestamp_granularities paramétert, hibázni fog. Mindig ellenőrizd a bemeneti paraméterek és a kimenetkezelés konzisztenciáját.

Paraméterkombinációk

Íme az öt érvényes kombináció, amelyekkel a leggyakrabban találkozhatsz, a legegyszerűbbtől a legspecializáltabbig.

# Egyszerű átírás (csak szöveg)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"}
)

# Kényszerített nyelvvel (időbélyegek nélkül)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Szegmens időbélyegekkel
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Beszélőazonosítással + időbélyegekkel
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Kontextus-biaszolással
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/audio.mp3",
    context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)

A Voxtral 2 meglepő korlátja az volt, hogy a language és a timestamp_granularities nem használható együtt ugyanabban a hívásban. A Voxtral 3 dokumentációja már nem említi ezt a korlátozást; teszteld le, mielőtt támaszkodnál rá.

Hitelesítés

Minden kéréshez érvényes API-kulcs szükséges, amelyet a kliens konstruktornak kell átadni. Fejlesztés közben elegendő a közvetlen argumentum. Éles környezetben használj környezeti változót, hogy megakadályozd a kulcs Git-tárolóba kerülését.

from mistralai.client import Mistral

# Közvetlen argumentummal
client = Mistral(api_key="your-api-key")

# Vagy környezeti változón keresztül (éles környezethez ajánlott)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Főbb megállapítások

  • A /audio/transcriptions végpont szinkron: elküldöd a fájlt, megkapod a szöveget.
  • Két feltöltési mód: közvetlen feltöltés (file) vagy nyilvános URL (file_url).
  • Opcionális paraméterek: language, timestamp_granularities, diarize, context_bias.
  • A Voxtral 2-ben a language és a timestamp_granularities kölcsönösen kizárták egymást; a Voxtral 3 dokumentációja már nem állítja ezt.
  • A gyakori hangformátumok támogatottak; a korlát a hanganyag és a context_bias között megosztott kontextusablak (túllépés esetén 400-as hiba).
  • A beszélőazonosítás és az időbélyegek kombinálhatók.