Alapvető beszédgenerálás
Ezen az oldalon
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-2603modellt, amelyet 2026. október 31-én elavulttá nyilvánítottak és 2027. április 30-án vontak vissza, a példákban avoxtral-mini-tts-3-0vá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, azexpressivenessbeá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 avoxtral-mini-tts-3-0modellel - 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