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

Alapvető beszédgenerálás

8. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Az első hanggenerálásod
  2. Mit szabályoz az egyes paraméterek?
  3. Skálázás: egy hangoskönyv-fejezet
  4. Amikor a generálás meghiúsul
  5. Főbb megállapítások

A tanfolyam frissítve: 2026. november 3., Voxtral TTS 3 verzió, a Migrálás a Voxtral 2-ről útmutató és a Mistral Szövegből beszéd (Text to Speech) oldalai alapján: a voxtral-mini-tts-2603 modellt, amelyet 2026. október 31-én elavulttá nyilvánítottak és 2027. április 30-án vontak vissza, a példákban a voxtral-mini-tts-3-0 váltotta fel. Az előre definiált Voxtral 2 hangok (pl. gb_jane_neutral…) továbbra is elfogadottak; a Voxtral 3 bevezeti a szövegben használható [emotion=…] és [pace=…] címkéket, az expressiveness beállítást, az egyéni kiejtést (phoneme_hints) és 35 nyelvet támogat. A Mistral ajánlja a késleltetés újbóli mérését a migrálás után. Források: Migrálás a Voxtral 2-ről · Beszédgenerálás.

Az első hanggenerálásod

Most már tudod, hogyan hozz létre hangot és hogyan kezeld azt a Voices API-n keresztül. Az utolsó lépés annak megvalósítása, amiért mindez az egész munka folyt: a hanganyag előállítása. A Mistral Speech API lényegében egyetlen hívásra redukálódik: a client.audio.speech.complete() metódusra, amely szöveget és egy hangazonosítót (voice ID) vár paraméterként, és base64 kódolású hangot ad vissza. Ez a lecke a mentett hanggal történő alapvető generálást tárgyalja; a valós idejű klónozás és az adatfolyam-alapú (streaming) megoldások a következőkben jönnek.

Az alábbi kód minden, amire szükséged van ahhoz, hogy egy mondatot MP3 fájllá alakíts a lemezeden. Figyelj nagyon az utolsó lépésre: a válasz nem tartalmaz közvetlenül használható nyers hangbájtokat, hanem egy base64 karakterláncot, amelyet dekódolnod kell, mielőtt fájlként elmented. Ez a klasszikus kezdő hiba: ha a karakterláncot változatlanul mented el, a lejátszók megtagadják a fájl megnyitását.

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Beszéd generálása egy mentett hanggal
response = client.audio.speech.complete(
    model="voxtral-mini-tts-3-0",
    input="Hello and welcome to this course on Voxtral TTS.",
    voice_id="your-voice-id",
    response_format="mp3",
)

# Base64 dekódolása és mentés fájlba
audio_bytes = base64.b64decode(response.audio_data)
Path("output.mp3").write_bytes(audio_bytes)
print(f"Audio generated: {len(audio_bytes)} bytes")

Mit szabályoz az egyes paraméterek?

A model paraméter határozza meg a szintézismodellt. Jelenleg a voxtral-mini-tts-3-0 az egyetlen elérhető modell, de mindig add meg explicit módon: ha később más modellek is megjelennek, a kódod akkor is pontosan ugyanazt a hangot állítja elő, mint ma.

Az input paraméter tartalmazza a felolvasandó szöveget, és ez igényli a legnagyobb figyelmet. A Voxtral 2 dokumentációja azt javasolta, hogy kérésenként maradj 300 szó alatt; a Voxtral TTS 3 dokumentációja már nem szab korlátot, de az egy bekezdéses kérések továbbra is könnyebben kezelhetők és lejátszhatók. Kerüld az emojikat, amelyeket a modell nem tud értelmezni, valamint a bonyolult formázásokat – Markdown, HTML, speciális karakterek –, mivel ezeket a rendszer szó szerint felolvassa. Végül írd ki betűvel a számokat és a rövidítéseket: „twenty-three“ a „23“ helyett, „Limited Liability Company“ az „LLC“ helyett. Az a hangalapú ügynök, amely a számoknál megakad egy összeg bemondása közben, egyetlen mondattal elveszíti a hitelességét.

A voice_id azonosítja a használt hangot. Háromféleképpen juthatsz hozzá: hang létrehozásával a client.audio.voices.create() segítségével (lásd az 5. leckét), a meglévő hangjaid listázásával a client.audio.voices.list() metódussal, vagy egy Mistral professzionális hang azonosítójának újrafelhasználásával. Végül a response_format állítja be a kimeneti formátumot a következők közül: mp3, wav, pcm, flac és opus. Ez a választás mind a fájlméretet, mind a késleltetést befolyásolja; a 12. lecke teljes egészében ezzel foglalkozik.

Skálázás: egy hangoskönyv-fejezet

Kicsit hosszabb szövegek esetén továbbra is a legjobb gyakorlat a szöveg felosztása. Az elv egyszerű: készíts elő egy bekezdésekből álló listát, generáld le őket külön-külön, majd a dekódolt bájtokat egyetlen pufferben gyűjtsd össze, mielőtt megírnád a végső fájlt.

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")
voice_id = "your-voice-id"

# Szöveg felosztva bekezdésekre
paragraphs = [
    "First paragraph of the chapter. The narrator introduces the context.",
    "Second paragraph. The action begins to develop.",
    "Third paragraph. Suspense builds gradually.",
]

full_audio = b""

for i, text in enumerate(paragraphs):
    print(f"Generating segment {i + 1}/{len(paragraphs)}...")
    response = client.audio.speech.complete(
        model="voxtral-mini-tts-3-0",
        input=text,
        voice_id=voice_id,
        response_format="wav",
    )
    full_audio += base64.b64decode(response.audio_data)

Path("chapter-01.wav").write_bytes(full_audio)
print("Audio chapter generated successfully!")

Ez a szkript azért működik, mert WAV formátumot állít elő, amely egy tömörítetlen formátum, így a szegmensei különleges feldolgozás nélkül, végüknél fogva összefűzhetők. Ha ugyanezt megpróbálod MP3-mal vagy Opusszal, az eredmény használhatatlan lesz: ezek a tömörített formátumok fejléceket és keretszerkezeteket tartalmaznak, amelyeket a nyers összefűzés tönkretesz. Ehelyett használj olyan könyvtárat, mint a pydub, amely minden szegmenst dekódol, mielőtt tisztán egyesítené őket.

Amikor a generálás meghiúsul

Éles környezetben védened kell a hívást. Egy kolléga által tegnap törölt voice_id, egy csendben meghosszabbodott szöveg egy mező összefűzése miatt, egy hónap végén kimerült API-kvóta vagy egy elgépelten megadott kimeneti formátum: mindezek a helyzetek kivételt (exception) dobnak, és védelmi mechanizmusok nélkül a kötegelt feldolgozásod a korpusz közepén megáll.

try:
    response = client.audio.speech.complete(
        model="voxtral-mini-tts-3-0",
        input="Text to convert to speech.",
        voice_id=voice_id,
        response_format="mp3",
    )
    audio_bytes = base64.b64decode(response.audio_data)
    Path("output.mp3").write_bytes(audio_bytes)
except Exception as e:
    print(f"Error during generation: {e}")

Szánj időt ennek a hibakezelési útvonalnak a tesztelésére, mielőtt élesbe teszed a rendszert: szándékosan generálj egy hamis voice_id-vel, és győződj meg róla, hogy az alkalmazásod egyértelműen jelzi a hibát, ahelyett, hogy egy üres fájlt hozna létre.

Főbb megállapítások

  • A generálás a client.audio.speech.complete() metódust használja a voxtral-mini-tts-3-0 modellel
  • Oszt fel hosszú szövegeket bekezdésekre, és kerüld az emojikat és a formázást
  • Írd ki betűvel a számokat és a rövidítéseket a helyes kiejtés érdekében
  • A visszaadott hang base64 kódolású – dekódold, mielőtt elmented
  • Hosszú szövegeknél oszd fel szegmensekre, és fűzd össze az eredményeket