A API de Vozes
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, preterido a 31 de outubro de 2026 e removido 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.
O Endpoint /v1/voices
A API de Vozes da Mistral é o seu ponto de entrada para gerir vozes personalizadas. Expõe um conjunto completo de operações CRUD — Criar, Ler, Atualizar, Eliminar — permitindo-lhe criar, listar, recuperar, modificar e eliminar vozes. Se já trabalhou com uma API REST padrão, está em terreno conhecido: nada aqui trata diretamente do processamento de áudio; isto diz respeito puramente à gestão de um catálogo de objetos.
Cada voz criada através da API recebe um identificador único, o voice_id, que utilizará posteriormente para gerar fala. Tenha isto em mente: as vozes são persistentes. Uma vez criadas, permanecem disponíveis na sua conta até serem explicitamente eliminadas. Não precisa de reenviar a amostra de áudio para cada geração, pelo que as suas aplicações apenas necessitam de armazenar uma cadeia de caracteres na sua configuração.
Criar uma Voz
A criação ocorre através de uma chamada POST ao endpoint /v1/voices. Fornece uma amostra de áudio codificada em base64 juntamente com metadados descritivos:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Codificar a amostra de áudio em base64
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Criar a voz
voice = client.audio.voices.create(
name="my-pro-voice",
sample_audio=sample_audio_b64,
sample_filename="sample.mp3",
languages=["fr", "en"],
gender="female",
age=35,
tags=["professional", "podcast"]
)
print(f"Voice created: {voice.id}")
A utilização de base64 é necessária porque o pedido é um documento JSON, e o JSON não consegue transportar dados binários. A API devolve um objeto contendo o voice_id que deverá guardar para todos os pedidos de geração. No exemplo acima, imprimimo-lo, mas em produção deve escrevê-lo na sua configuração ou base de dados.
Listar, Recuperar e Modificar
Para obter uma lista de todas as suas vozes, o método list() suporta paginação:
# Obter as primeiras 10 vozes
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
A paginação é baseada em deslocamento (offset): especifica o número de itens com limit e o ponto de partida com offset. Para navegar também nas vozes predefinidas da Mistral (Marie em francês, fr_marie_neutral, Jane em inglês britânico, etc.), voices.search lista ambas as famílias, distinguindo-as pelo campo type: preset ou custom. Para obter a segunda página de dez vozes, chama o método com offset=10. Este mecanismo torna-se útil assim que uma agência gere vozes para dezenas de clientes.
Quando necessitar de detalhes sobre uma voz específica, get() devolve os seus metadados completos:
voice = client.audio.voices.get(voice_id="your-voice-id")
print(f"Name: {voice.name}")
print(f"Gender: {voice.gender}")
print(f"Languages: {voice.languages}")
print(f"Tags: {voice.tags}")
Adote o hábito de chamar esta operação antes de uma grande execução de geração. Isto verifica se o voice_id codificado na sua aplicação aponta para a voz esperada e não para uma de um projeto antigo.
Pode modificar os metadados de uma voz existente sem tocar na amostra de áudio:
updated_voice = client.audio.voices.update(
voice_id="your-voice-id",
name="my-pro-voice-v2",
languages=["fr", "en", "es"],
tags=["professional", "podcast", "multilingual"]
)
print(f"Voice updated: {updated_voice.name}")
Os campos modificáveis incluem name, languages, gender, age, tags e description. A amostra de áudio original, no entanto, não pode ser modificada. Se quiser alterar o áudio, deve criar uma nova voz. Na prática, uma voz mal gravada não pode ser reparada — deve ser substituída, e terá de propagar o novo voice_id pelas suas aplicações.
Eliminar e Recuperar a Amostra
A eliminação é permanente e irreversível:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Após a eliminação, qualquer pedido de geração que utilize esse voice_id falhará. Um cenário clássico de pesadelo: um programador limpa vozes de teste, elimina acidentalmente uma que está realmente a alimentar o IVR de suporte, e o incidente rebenta na manhã seguinte na primeira chamada recebida. Certifique-se sempre de que as suas aplicações estão atualizadas antes de eliminar uma voz em produção.
Também pode descarregar o áudio original utilizado para criar uma voz:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Esta funcionalidade ajuda-o a arquivar as suas amostras ou a verificar a qualidade do áudio de origem se uma voz o dececionar. Ao ouvir o original, descobre frequentemente que a falha ouvida durante a geração já estava presente na gravação.
Organizar o Seu Catálogo de Vozes
Uma gestão limpa custa pouco e previne confusões significativas. Nomeie as suas vozes claramente com um prefixo de projeto, seguindo padrões como podcast-narrator ou app-assistant-fr, em vez de voice1 e test-final-2. Utilize etiquetas para categorizar por caso de uso, projeto ou cliente, tornando as listas geríveis à medida que crescem. Documente os voice_ids na configuração da sua aplicação, nunca num ficheiro isolado numa estação de trabalho. E nunca elimine uma voz de produção sem primeiro verificar que já não é referenciada em lado nenhum.
Pontos-chave
- A API de Vozes expõe capacidades CRUD completas: criar, listar, recuperar, atualizar, eliminar
- Cada voz recebe um
voice_idúnico utilizado nos pedidos de geração - A paginação baseada em deslocamento permite gerir um grande número de vozes
- A eliminação é permanente — todos os pedidos que utilizem esse voice_id falharão
- A amostra de áudio original pode ser recuperada através do endpoint de amostras