Przejdź do głównej treści
Polski— Wybierz język
Menu

Podstawowe generowanie mowy

Lekcja 8 z 14 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Twoje pierwsze generowanie głosu
  2. Co kontroluje każdy parametr
  3. Skalowanie: rozdział audiobooka
  4. Kiedy generowanie zawiedzie
  5. Kluczowe wnioski

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 modelem voxtral-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, ustawienie expressiveness, 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 modelem voxtral-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