Премини към основното съдържание
Български— Изберете език
Меню

Генериране на основна реч

Урок 8 от 14 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Първото Ви генериране на глас
  2. Какво контролира всеки параметър
  3. Мащабиране: Глава от аудиокнига
  4. Когато генерирането се провали
  5. Ключови изводи

Курсът е актуализиран на 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 – декодирайте го преди запазване
  • За дълги текстове ги разделете на сегменти и конкатенирайте резултатите