Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Geração Básica de Fala

Aula 8 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A Sua Primeira Geração de Voz
  2. O Que Cada Parâmetro Controla
  3. Escalar: Um Capítulo de Audiobook
  4. Quando a Geração Falha
  5. Pontos-chave

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 por voxtral-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ção expressiveness, 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 modelo voxtral-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