Генериране на основна реч
На тази страница
Курсът е актуализиран на 3 ноември 2026 г. за Voxtral TTS 3, въз основа на ръководството Migrate from Voxtral 2 и страниците на Mistral за Text to Speech:
voxtral-mini-tts-2603, обявен за остарял на 31 октомври 2026 г. и преустановен на 30 април 2027 г., е заменен в примерите сvoxtral-mini-tts-3-0. Предварително дефинираните гласове на Voxtral 2 (gb_jane_neutral…) остават поддържани; Voxtral 3 добавя тагове[emotion=…]и[pace=…]в текста, настройкатаexpressiveness, персонализирано произношение (phoneme_hints) и 35 езика. Mistral препоръчва повторно измерване на латентността след миграцията. Източници: Migrate from Voxtral 2 · Speech generation.
Първото Ви генериране на глас
Вече знаете как да създадете глас и да го управлявате чрез Voices API. Последната стъпка е да постигнете целта на цялата тази работа: да произведете аудио. Speech API на Mistral се свежда до едно единствено извикване – client.audio.speech.complete(), което приема текст и ID на глас и връща аудио, кодирано в base64. Този урок обхваща основното генериране със запазен глас; клонирането в реално време и стриймингът ще следват в следващите уроци.
Кодът по-долу е всичко, от което се нуждаете, за да превърнете изречение в MP3 файл на Вашия диск. Обърнете специално внимание на последната стъпка: отговорът не съдържа сурови аудио байтове, които можете да използвате директно, а низ в base64, който трябва да декодирате, преди да запишете файла. Това е класическата грешка за начинаещи – запазването на низа такъв, какъвто е, кара аудио плейърите да откажат да го отворят.
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")
Какво контролира всеки параметър
Параметърът model определя модела за синтез. Към днешна дата voxtral-mini-tts-3-0 е единственият наличен, но винаги го посочвайте изрично: когато се появят други модели, Вашият код ще продължи да произвежда точно същия глас, както и днес.
input приема текста за изговаряне и това е параметърът, изискващ най-голямо внимание. Документацията на Voxtral 2 съветваше да се остава под 300 думи на заявка; документацията на Voxtral TTS 3 вече не задава лимит, но заявките с един абзац остават по-лесни за контрол и възпроизвеждане. Избягвайте емотикони, които моделът не може да интерпретира, както и сложно форматиране – Markdown, HTML, специални символи – което в крайна сметка се прочита дословно. Накрая, изписвайте числата и съкращенията с думи: „двадесет и три“ вместо „23“, „Дружество с ограничена отговорност“ вместо „ООД“. Гласов агент, който се спъва в числата, докато обявява сума, губи доверие още в първото изречение.
voice_id идентифицира използвания глас. Можете да го получите по три начина: чрез създаване на глас с client.audio.voices.create() (виж урок 5), чрез изброяване на съществуващите Ви гласове с client.audio.voices.list() или чрез повторно използване на ID на професионален глас на Mistral. Накрая, response_format задава изходния формат измежду mp3, wav, pcm, flac и opus. Този избор влияе както върху размера на файла, така и върху латентността, а урок 12 е изцяло посветен на него.
Мащабиране: Глава от аудиокнига
За малко по-дълги текстове разделянето остава най-добрата практика. Принципът е прост: подгответе списък с абзаци, генерирайте всеки от тях поотделно, след което натрупайте декодираните байтове в един буфер, преди да запишете крайния файл.
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!")
Този скрипт работи, защото произвежда WAV – некомпресиран формат, чиито сегменти могат да се конкатенират край до край без специална обработка. Опитайте същото с MP3 или Opus и резултатът ще бъде неизползваем: тези компресирани формати съдържат хедъри и структури на кадри, които суровата конкатенация нарушава. Вместо това използвайте библиотека като pydub, която декодира всеки сегмент, преди да ги обедини правилно.
Когато генерирането се провали
В производствена среда трябва да защитите извикването. Изтрит вчера от колега voice_id, текст, който тихо нараства, защото поле е било конкатенирано, изчерпан API квота в края на месеца, грешно изписан изходен формат: всяка от тези ситуации поражда изключение и без предпазни мерки Вашата пакетна обработка спира по средата на корпуса.
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}")
Отделете време да тествате този път за обработка на грешки, преди да преминете в продукция: умишлено генерирайте с невалиден voice_id и проверете дали Вашето приложение сигнализира за това ясно, вместо да произвежда празен файл.
Ключови изводи
- Генерирането използва
client.audio.speech.complete()с моделvoxtral-mini-tts-3-0 - Разделяйте дългите текстове на абзаци и избягвайте емотикони и форматиране
- Изписвайте числата и съкращенията с думи за правилно произношение
- Върнатото аудио е в base64 – декодирайте го преди запазване
- За дълги текстове ги разделете на сегменти и конкатенирайте резултатите