Podstawowe generowanie mowy
Na tej stronie
Kurs zaktualizowano 3 listopada 2026 r. dla Voxtral TTS 3, na podstawie przewodnika Migrate from Voxtral 2 oraz dokumentacji Mistral dotyczącej Text to Speech: model
voxtral-mini-tts-2603, przestarzały od 31 października 2026 r. i wycofany 30 kwietnia 2027 r., został zastąpiony w przykładach modelemvoxtral-mini-tts-3-0. Predefiniowane głosy Voxtral 2 (gb_jane_neutral…) są nadal obsługiwane; Voxtral 3 wprowadza tagi[emotion=…]i[pace=…]w tekście, ustawienieexpressiveness, niestandardową wymowę (phoneme_hints) oraz obsługę 35 języków. Mistral zaleca ponowne zmierzenie opóźnień po migracji. Źródła: Migrate from Voxtral 2 · Speech generation.
Twoje pierwsze generowanie głosu
Wiesz już, jak stworzyć głos i zarządzać nim za pomocą interfejsu API Voices. Ostatnim krokiem jest zrobienie tego, dla czego wykonywałeś całą tę pracę: wygenerowanie dźwięku. Interfejs API Speech od Mistral sprowadza się do jednego wywołania, client.audio.speech.complete(), które przyjmuje tekst i identyfikator głosu, a zwraca dźwięk zakodowany w formacie base64. Ta lekcja obejmuje podstawowe generowanie z zapisanym głosem; klonowanie w locie i strumieniowanie omówimy w następnej kolejności.
Poniższy kod to wszystko, czego potrzebujesz, aby zamienić zdanie w plik MP3 na swoim dysku. Zwróć szczególną uwagę na ostatni krok: odpowiedź nie zawiera surowych bajtów audio, których możesz użyć bezpośrednio, lecz ciąg base64, który musisz zdekodować przed zapisaniem pliku. To klasyczny błąd początkujących – zapisanie ciągu „jak leci“ sprawia, że odtwarzacze audio odmawiają otwarcia pliku.
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Generate speech with a saved voice
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",
)
# Decode base64 and save to file
audio_bytes = base64.b64decode(response.audio_data)
Path("output.mp3").write_bytes(audio_bytes)
print(f"Audio generated: {len(audio_bytes)} bytes")
Co kontroluje każdy parametr
Parametr model określa model syntezy. Obecnie dostępny jest tylko voxtral-mini-tts-3-0, ale zawsze podawaj go jawnie: gdy pojawią się inne modele, Twój kod będzie nadal generował dokładnie ten sam głos co dzisiaj.
Parametr input przyjmuje tekst do wypowiedzenia i jest to zdecydowanie parametr wymagający największej uwagi. Dokumentacja Voxtral 2 zalecała pozostawanie poniżej 300 słów na żądanie; dokumentacja Voxtral TTS 3 nie określa już limitu, ale żądania obejmujące pojedyncze akapity są nadal łatwiejsze do kontrolowania i odtwarzania. Unikaj emoji, których model nie potrafi zinterpretować, a także złożonego formatowania – Markdown, HTML, znaki specjalne – które zostaną odczytane dosłownie. Na koniec zapisuj liczby i skróty słownie: „dwadzieścia trzy“ zamiast „23“, „spółka z ograniczoną odpowiedzialnością“ zamiast „Sp. z o.o.“. Agent głosowy, który zacina się przy liczbach podczas ogłaszania kwoty, traci wiarygodność w ciągu jednego zdania.
voice_id identyfikuje używany głos. Możesz go uzyskać na trzy sposoby: tworząc głos za pomocą client.audio.voices.create() (zobacz lekcję 5), wyświetlając listę istniejących głosów za pomocą client.audio.voices.list() lub ponownie używając identyfikatora profesjonalnego głosu Mistral. Parametr response_format ustawia natomiast format wyjściowy spośród: mp3, wav, pcm, flac i opus. Wybór ten wpływa zarówno na rozmiar pliku, jak i na opóźnienie; lekcja 12 jest poświęcona temu zagadnieniu w całości.
Skalowanie: rozdział audiobooka
W przypadku nieco dłuższych tekstów najlepszą praktyką pozostaje podział. Zasada jest prosta: przygotuj listę akapitów, wygeneruj każdy z nich osobno, a następnie zgromadź zdekodowane bajty w jednym buforze przed zapisaniem końcowego pliku.
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
voice_id = "your-voice-id"
# Text split into paragraphs
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!")
Ten skrypt działa, ponieważ produkuje format WAV, nieskompresowany format, którego segmenty można łączyć koniec do końca bez specjalnego przetwarzania. Spróbuj zrobić to samo z MP3 lub Opus, a wynik będzie niezdatny do użycia: te formaty skompresowane zawierają nagłówki i struktury klatek, które surowe łączenie niszczy. Zamiast tego użyj biblioteki takiej jak pydub, która dekoduje każdy segment przed ich czystym połączeniem.
Kiedy generowanie zawiedzie
W środowisku produkcyjnym musisz zabezpieczyć wywołanie. Usunięty wczoraj przez kolegę voice_id, tekst, który po cichu rośnie, ponieważ pole zostało połączone, wyczerpany limit API pod koniec miesiąca, literówka w formacie wyjściowym: każda z tych sytuacji powoduje zgłoszenie wyjątku, a bez zabezpieczeń Twoje przetwarzanie wsadowe zatrzyma się w połowie korpusu.
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}")
Poświęć czas na przetestowanie tej ścieżki obsługi błędów przed wdrożeniem do produkcji: celowo wygeneruj dźwięk z nieprawidłowym voice_id i sprawdź, czy Twoja aplikacja sygnalizuje to wyraźnie, zamiast tworzyć pusty plik.
Kluczowe wnioski
- Generowanie wykorzystuje
client.audio.speech.complete()z modelemvoxtral-mini-tts-3-0 - Dziel długie teksty na akapity i unikaj emoji oraz formatowania
- Zapisuj liczby i skróty słownie, aby zapewnić poprawną wymowę
- Zwracane audio jest w formacie base64 – zdekoduj je przed zapisaniem
- W przypadku długich tekstów podziel je na segmenty i połącz wyniki