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

A API de Vozes

Aula 4 de 14 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O Endpoint /v1/voices
  2. Criar uma Voz
  3. Listar, Recuperar e Modificar
  4. Eliminar e Recuperar a Amostra
  5. Organizar o Seu Catálogo de Vozes
  6. Pontos-chave

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 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.

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