Geração Básica de Fala
Nesta página
Curso atualizado em 3 de novembro de 2026 para o Voxtral TTS 3, com base no guia Migrate from Voxtral 2 e nas páginas Text to Speech da Mistral: o modelo
voxtral-mini-tts-2603, descontinuado a 31 de outubro de 2026 e retirado a 30 de abril de 2027, é substituído nos exemplos porvoxtral-mini-tts-3-0. As vozes predefinidas do Voxtral 2 (gb_jane_neutral…) continuam a ser aceites; o Voxtral 3 adiciona as etiquetas[emotion=…]e[pace=…]no texto, a definiçãoexpressiveness, a pronúncia personalizada (phoneme_hints) e suporte para 35 idiomas. A Mistral recomenda voltar a medir a latência após a migração. Fontes: Migrate from Voxtral 2 · Speech generation.
A Sua Primeira Geração de Voz
Agora sabe como criar uma voz e geri-la através da API de Vozes. O passo final é fazer aquilo para que todo este trabalho serviu: produzir áudio. A API de Fala da Mistral resume-se a uma única chamada, client.audio.speech.complete(), que recebe texto e um ID de voz e devolve áudio codificado em base64. Esta lição abrange a geração básica com uma voz guardada; a clonagem em tempo real e a transmissão em fluxo contínuo virão a seguir.
O código abaixo é tudo o que precisa para transformar uma frase num ficheiro MP3 no seu disco. Preste muita atenção ao último passo: a resposta não contém bytes de áudio brutos que possa utilizar diretamente, mas sim uma cadeia base64 que deve descodificar antes de escrever o ficheiro. Este é o erro clássico de principiante — guardar a cadeia tal como está faz com que os leitores de áudio se recusem a abri-la.
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")
O Que Cada Parâmetro Controla
O parâmetro model especifica o modelo de síntese. Até à data, voxtral-mini-tts-3-0 é o único disponível, mas deve especificá-lo sempre explicitamente: quando surgirem outros modelos, o seu código continuará a produzir exatamente a mesma voz que produz hoje.
O parâmetro input recebe o texto a falar e é, de longe, o que requer mais atenção. A documentação do Voxtral 2 aconselhava a manter-se abaixo de 300 palavras por pedido; a documentação do Voxtral TTS 3 já não define um limite, mas os pedidos de parágrafo único continuam a ser mais fáceis de controlar e reproduzir. Evite emojis, que o modelo não consegue interpretar, bem como formatação complexa — Markdown, HTML, caracteres especiais — que acaba por ser lida literalmente. Por fim, escreva por extenso os números e as abreviaturas: «vinte e três» em vez de «23», «Sociedade por Quotas» em vez de «Lda.». Um agente de voz que tropece em números ao anunciar um valor perde credibilidade numa única frase.
O voice_id identifica a voz utilizada. Pode obtê-lo de três formas: criando uma voz com client.audio.voices.create() (ver lição 5), listando as suas vozes existentes com client.audio.voices.list(), ou reutilizando o ID de uma voz profissional da Mistral. Finalmente, o response_format define o formato de saída entre mp3, wav, pcm, flac e opus. Esta escolha afeta tanto o tamanho do ficheiro como a latência, e a lição 12 é inteiramente dedicada a este tema.
Escalar: Um Capítulo de Audiobook
Para textos ligeiramente mais longos, a divisão continua a ser a melhor prática. O princípio é simples: prepare uma lista de parágrafos, gere cada um separadamente e, em seguida, acumule os bytes descodificados num único buffer antes de escrever o ficheiro final.
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!")
Este script funciona porque produz WAV, um formato não comprimido cujos segmentos se concatenam de ponta a ponta sem processamento especial. Tente fazer o mesmo com MP3 ou Opus e o resultado será inutilizável: estes formatos comprimidos contêm cabeçalhos e estruturas de quadros que a concatenação bruta quebra. Em vez disso, utilize uma biblioteca como a pydub, que descodifica cada segmento antes de os fundir corretamente.
Quando a Geração Falha
Em produção, deve proteger a chamada. Um voice_id eliminado ontem por um colega, texto que cresce silenciosamente porque um campo foi concatenado, uma quota de API esgotada no final do mês, um formato de saída escrito incorretamente: cada uma destas situações levanta uma exceção e, sem salvaguardas, o seu processamento em lote para a meio do corpus.
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}")
Dedique tempo a testar este caminho de erro antes de ir para produção: gere deliberadamente com um voice_id inválido e verifique se a sua aplicação o sinaliza claramente, em vez de produzir um ficheiro vazio.
Pontos-chave
- A geração utiliza
client.audio.speech.complete()com o modelovoxtral-mini-tts-3-0 - Divida textos longos em parágrafos e evite emojis e formatação
- Escreva por extenso números e abreviaturas para uma pronúncia correta
- O áudio devolvido está em base64 — descodifique-o antes de guardar
- Para textos longos, divida em segmentos e concatene os resultados