Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Põhiline kõne genereerimine

Õppetund 8 / 14 Värskendatud 3. november 2026 Arendajatele
Sellel lehel
  1. Sinu esimene hääle genereerimine
  2. Mida iga parameeter juhib
  3. Mastaabi suurendamine: kuuldaraamatu peatükk
  4. Kui genereerimine ebaõnnestub
  5. Peamised punktid

Kursust uuendati 3. novembril 2026 Voxtral TTS 3 jaoks, tuginedes Migrate from Voxtral 2 juhendile ja Mistrali Text to Speech lehekülgedele: voxtral-mini-tts-2603, mis tunnistati aegunuks 31. oktoobril 2026 ja eemaldatakse kasutusest 30. aprillil 2027, on näidetes asendatud mudeliga voxtral-mini-tts-3-0. Eelmääratletud Voxtral 2 hääled (gb_jane_neutral…) on endiselt aktsepteeritud; Voxtral 3 lisab teksti sisse sildid [emotion=…] ja [pace=…], seadistuse expressiveness, kohandatud häälduse (phoneme_hints) ning toetab 35 keelt. Mistral soovitab pärast migreerimist latentsusaeg uuesti mõõta. Allikad: Migrate from Voxtral 2 · Kõne genereerimine.

Sinu esimene hääle genereerimine

Nüüd tead, kuidas häält luua ja seda Voices API kaudu hallata. Viimane samm on teha see, mille jaoks kogu see töö ette võeti: heli tootmine. Mistrali kõne API taandub üheleainsale väljakutsele, client.audio.speech.complete(), mis võtab sisendiks teksti ja hääle ID ning tagastab base64-kodeeringus helifaili. See õppetund käsitleb põhilist genereerimist salvestatud häälega; reaalajas kloonimine ja voogedastus tulevad järgmiseks.

Allpool olev kood on kõik, mida vajad lause MP3-failiks muutmiseks oma kõvakettal. Pööra erilist tähelepanu viimasele sammule: vastus ei sisalda tooreid helibaitte, mida saaksid otse kasutada, vaid base64-stringi, mille pead enne faili kirjutamist dekodeerima. See on klassikaline esmakordne viga – stringi sellisena salvestamine põhjustab helimängijate keeldumist faili avada.

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

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

# Genereeri kõne salvestatud häälega
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",
)

# Dekodeeri base64 ja salvesta faili
audio_bytes = base64.b64decode(response.audio_data)
Path("output.mp3").write_bytes(audio_bytes)
print(f"Audio generated: {len(audio_bytes)} bytes")

Mida iga parameeter juhib

Parameeter model määrab sünteesimudeli. Praegu on ainus saadaval voxtral-mini-tts-3-0, kuid määra see alati sõnaselgelt: kui ilmuvad teised mudelid, jätkab sinu kood täpselt sama hääle tootmist, mida ta teeb täna.

input võtab vastu räägitava teksti ja see on kaugelt kõige rohkem tähelepanu nõudev parameeter. Voxtral 2 dokumentatsioon soovitas jääda alla 300 sõna päringu kohta; Voxtral TTS 3 dokumentatsioon enam piiranguid ei sea, kuid ühe lõigu pikkused päringud on endiselt lihtsamini hallatavad ja taasesitatavad. Välti emojisid, mida mudel tõlgendada ei oska, samuti keerukat vormindust – Markdown, HTML, erimärgid –, mis loetakse sõna-sõnalt ette. Lõpuks kirjuta numbrid ja lühendid täisnimes: „kakskümmend kolm“ asemel „23“, „osaühing“ asemel „OÜ“. Häälagent, kes summa väljahüüdmisel numbritega komistab, kaotab usaldusväärsuse ühe lausega.

voice_id tuvastab kasutatava hääle. Saad selle kolmel viisil: luues hääle käsuga client.audio.voices.create() (vaata õppetundi 5), loetledes oma olemasolevad hääled käsuga client.audio.voices.list() või kasutades uuesti Mistrali professionaalse hääle ID-d. response_format määrab lõpuks väljundformaadi valikutest mp3, wav, pcm, flac ja opus. See valik mõjutab nii faili suurust kui ka latentsusaega ja õppetund 12 on pühendatud täielikult just sellele.

Mastaabi suurendamine: kuuldaraamatu peatükk

Pikema teksti puhul on parimaks tavaks selle tükeldamine. Põhimõte on lihtne: valmista ette lõikude loend, genereeri üks haaval ja kogu dekodeeritud baidid ühte puhvrisse enne lõpliku faili kirjutamist.

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

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

# Tekst jagatud lõikudeks
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!")

See skript töötab, kuna see toodab WAV-i, tihendamata formaadi, mille segmente saab liita ots-otsa ilma eritöötluseta. Proovi sama teha MP3 või Opus’ega ja tulemus on kasutu: need tihendatud formaadid sisaldavad päiseid ja kaadristruktuure, mida toore liitmine rikub. Selle asemel kasuta teeki nagu pydub, mis dekodeerib iga segmendi enne nende puhtalt ühendamist.

Kui genereerimine ebaõnnestub

Tootmiskeskkonnas pead väljakutset kaitsma. Eile kolleegi poolt kustutatud voice_id, tekst, mis vaikselt pikeneb välja liitmise tõttu, kuu lõpus ammendunud API kvoot, valesti kirjutatud väljundformaad: igaüks neist olukordadest tõstab erindi ja ilma kaitsemeetmeteta peatub sinu partii-töötlus korpuse keskel.

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}")

Võta aega, et testida seda veaharus enne tootmisse viimist: genereeri tahtlikult vigase voice_id-ga ja veendu, et sinu rakendus annab sellest selgelt märku, mitte ei tooda tühja faili.

Peamised punktid

  • Genereerimine kasutab client.audio.speech.complete() mudeliga voxtral-mini-tts-3-0
  • Jaota pikad tekstid lõikudeks ning välti emojisid ja vormindust
  • Kirjuta numbrid ja lühendid täisnimes õige häälduse tagamiseks
  • Tagastatud heli on base64-kodeeringus – dekodeeri see enne salvestamist
  • Pikemate tekstide puhul jaga need segmentideks ja liida tulemused