Clonagem de Voz em Tempo Real
Nesta página
Curso atualizado a 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.
Clonar sem Guardar
A lição anterior baseava-se numa voz guardada, criada previamente através da API de Vozes e referenciada pelo seu voice_id. O Voxtral oferece um segundo caminho: a clonagem em tempo real, na qual fornece o áudio de referência diretamente no pedido de geração. Não é criado nenhum objeto na sua conta: a amostra serve apenas para esse pedido específico e é depois descartada.
Na prática, substitui voice_id por ref_audio, que espera a amostra de áudio codificada em base64. O restante da chamada permanece inalterado.
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Codificar o áudio de referência
ref_audio_b64 = base64.b64encode(
Path("reference.mp3").read_bytes()
).decode()
# Gerar com clonagem em tempo real
response = client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="Esta fala assemelhar-se-á à voz de referência.",
ref_audio=ref_audio_b64,
response_format="wav",
)
audio_bytes = base64.b64decode(response.audio_data)
Path("cloned-output.wav").write_bytes(audio_bytes)
print("Áudio gerado com clonagem em tempo real!")
Três Cenários onde esta Abordagem se Destaca
O primeiro é a prototipagem. Quando está à procura da amostra de referência ideal, pode testar dez, quinze ou até mais. Criar tantas vozes na sua conta significa que terá depois de as encontrar e apagar uma a uma. Com ref_audio, o seu ciclo de testes não deixa rasto no servidor, permitindo-lhe comparar as renderizações simplesmente ouvindo os ficheiros produzidos.
# Testar rapidamente várias amostras
samples = ["sample1.mp3", "sample2.mp3", "sample3.mp3"]
for file in samples:
ref_b64 = base64.b64encode(Path(file).read_bytes()).decode()
response = client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="Este é um teste de qualidade de voz.",
ref_audio=ref_b64,
response_format="mp3",
)
output = f"test-{Path(file).stem}.mp3"
Path(output).write_bytes(base64.b64decode(response.audio_data))
print(f"Gerado: {output}")
O segundo cenário é o uso ocasional. Uma mensagem de aniversário personalizada com a voz de um ente querido, ou uma demonstração para um cliente preparada para uma reunião específica: se a voz for usada apenas uma vez, não há razão para a instalar permanentemente na sua conta.
O terceiro é a confidencialidade. O áudio de referência enviado via ref_audio não é armazenado no servidor. Se estiver a lidar com a voz de um paciente, de uma testemunha ou de um executivo, esta diferença não é cosmética: altera o que deve declarar no seu registo de processamento e o que precisa de apagar no caso de um pedido.
voice_id vs. ref_audio: As Diferenças
| Critério | voice_id | ref_audio |
|---|---|---|
| Persistência | Voz guardada na conta | Sem persistência |
| Reutilização | Ilimitada | Por pedido |
| Latência | Ligeiramente mais rápida (voz já processada) | Ligeiramente mais lenta (processamento em cada chamada) |
| Gestão | CRUD completo (modificar, apagar) | Nada para gerir |
| Custo de Rede | Apenas o voice_id (alguns bytes) | Áudio completo em cada pedido |
| Confidencialidade | Áudio armazenado na nuvem | Áudio não armazenado |
A regra de decisão resume-se à frequência de uso. Uma voz usada todos os dias — como um narrador de aplicação ou um porta-voz de marca — merece ser criada com client.audio.voices.create(): poupa a largura de banda de enviar uma amostra em cada chamada e ganha no tempo de processamento da referência. Uma voz que está a testar ou que usará apenas uma vez deve passar por ref_audio, não lhe deixando nada para limpar.
Combinar Ambas as Abordagens
Estes dois métodos não são mutuamente exclusivos; o fluxo de trabalho mais eficaz coloca-os em sequência. Primeiro, encontre a amostra certa usando ref_audio, ouvindo cada resultado. Assim que um candidato o satisfizer, reutilize essa mesma cadeia base64 — já na memória — para criar a voz final, completa com o seu nome, idiomas e género.
# Fase 1: Teste rápido com ref_audio
ref_b64 = base64.b64encode(Path("my-voice.mp3").read_bytes()).decode()
response = client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="Teste de qualidade.",
ref_audio=ref_b64,
response_format="mp3",
)
# Ouvir o resultado...
# Fase 2: Satisfeito? Guardar a voz
voice = client.audio.voices.create(
name="my-validated-voice",
sample_audio=ref_b64,
sample_filename="my-voice.mp3",
languages=["fr"],
gender="male",
)
print(f"Voz guardada: {voice.id}")
Pratique com três gravações da sua própria voz, feitas em três condições diferentes — microfone de auscultadores, telemóvel, sala com reverberação. Gere a mesma frase com cada uma via ref_audio, ouça e, em seguida, guarde apenas a vencedora. Em dez minutos, aprenderá o que distingue uma boa amostra de uma má, sem deixar para trás três vozes inúteis.
Pontos-chave
- O parâmetro
ref_audiopermite clonar uma voz sem a guardar - O áudio de referência é codificado em base64 e enviado diretamente no pedido
- A clonagem em tempo real é ideal para testes, uso ocasional e confidencialidade
- Para uso regular, prefira uma voz guardada (menor latência, menos largura de banda)
- Pode testar com
ref_audioe depois guardar a voz assim que estiver satisfeito