A API de Transcrição Offline
Nesta página
Curso atualizado a 3 de novembro de 2026 para o Voxtral 3, com base no guia Migrate from Voxtral 2 da Mistral: os modelos Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), descontinuados a 31 de outubro de 2026 e retirados a 30 de abril de 2027, são substituídos nos exemplos porvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3evoxtral-mini-tts-3-0. Alterações principais: as marcas temporais são apenas por segmento (worddevolve um erro 400), a diarização em tempo real é suportada, as definições da sessão em tempo real ficam bloqueadas após o primeiro bloco de áudio e as entradas decontext_biassão de formato livre (frases com espaços). Fontes: Migrate from Voxtral 2 · Speech to Text.
O endpoint de transcrição
A API de transcrição offline da Mistral utiliza o endpoint /audio/transcriptions. Trata-se de uma API síncrona: envia um ficheiro de áudio, o pedido mantém-se aberto durante o processamento e recebe a transcrição completa na resposta. Não há nenhum ID de tarefa para consultar nem nenhum webhook para configurar. Isto simplifica significativamente o seu código, mas deve permitir tempos limite generosos para ficheiros longos.
Antes de começar a programar, certifique-se de que tem três pré-requisitos: uma conta na plataforma Mistral (console.mistral.ai), uma chave de API ativa e o SDK Python instalado.
Instalação do SDK
pip install mistralai
Parâmetros da chamada
Tudo passa por client.audio.transcriptions.complete(). Dois parâmetros são obrigatórios e quatro são opcionais. Estes parâmetros opcionais são o que transforma uma transcrição bruta num entregável utilizável.
Parâmetros obrigatórios
model— O identificador do modelo. Para transcrição offline, utilize"voxtral-mini-transcribe-3"(recomendado) ou uma versão fixa como"voxtral-mini-transcribe-3".fileoufile_url— O ficheiro de áudio a transcrever. Tem duas opções:file: Um dicionário{"content": file_object, "file_name": "name.mp3"}para carregamento direto.file_url: Um URL público que aponta para o ficheiro de áudio.
Escolher entre file e file_url é uma decisão arquitetural. Se o seu áudio já estiver armazenado num local publicamente acessível, file_url evita encaminhar o ficheiro através do seu servidor. Se o ficheiro vier do dispositivo de um utilizador ou de um armazenamento privado, o carregamento direto é necessário.
Parâmetros opcionais
Quatro definições opcionais alteram a natureza do resultado.
language espera um código de idioma ISO, como "fr" ou "en", e ignora a deteção automática. Force esta opção para lotes homogéneos, como um catálogo de entrevistas realizadas inteiramente em francês, para evitar que uma breve passagem em inglês altere o modelo a meio do ficheiro. Note que é incompatível com timestamp_granularities.
timestamp_granularities aceita a lista ["segment"] e aciona o retorno de marcas temporais segmento a segmento. Com o Voxtral 3, a granularidade word já não existe e devolve um erro 400. Este parâmetro permite ficheiros de legendas sincronizados com vídeo ou passagens indexadas numa conferência de duas horas.
diarize é um booleano. Quando definido como True, o modelo identifica os oradores e atribui cada segmento a um deles. Para um comité executivo de seis pessoas, isto faz a diferença entre uma parede de texto anónima e um relatório onde cada compromisso é atribuível.
Por fim, context_bias aceita uma lista de termos — uma única palavra ou uma frase com espaços, como o nome de um produto — para melhorar o reconhecimento de vocabulário específico. O número de entradas já não é fixo, mas partilham a janela de contexto com o áudio, por isso mantenha a lista curta. Uma reunião de engenharia com termos como “Kubernetes” e “GDPR” torna-se significativamente mais legível com esta definição.
Formatos de áudio suportados
O Voxtral aceita formatos de áudio comuns e raramente precisará de converter qualquer coisa antecipadamente. Em caso de dúvida, consulte a página Audio formats na documentação.
| Formato | Característica |
|---|---|
| MP3 | Mais comum, boa compressão |
| WAV | Sem compressão, qualidade máxima |
| FLAC | Compressão sem perdas |
| OGG | Formato aberto, boa compressão |
| M4A / AAC | Formato Apple, comum em telemóveis |
| WEBM | Formato web, comum para gravações no navegador |
O limite crítico é a janela de contexto do modelo, que é partilhada entre o áudio e o vocabulário context_bias. Um pedido que exceda este limite é rejeitado com um erro 400; a API não trunca o ficheiro. Para ficheiros muito longos, como um seminário de um dia inteiro, divida-os antes de enviar, de preferência em pontos de silêncio para evitar cortar frases a meio.
Estrutura da resposta
A resposta contém, no mínimo, o texto transcrito:
response.text # O texto transcrito completo (str)
Se tiver solicitado marcas temporais (timestamp_granularities), a resposta inclui também:
response.segments # Lista de segmentos com início, fim, texto
Se tiver ativado a diarização (diarize=True), cada segmento inclui a identidade do orador:
segment.speaker_id # Identificador do orador (str)
segment.start # Tempo de início em segundos (float)
segment.end # Tempo de fim em segundos (float)
segment.text # Texto do segmento (str)
Em suma, a forma do objeto devolvido depende do seu pedido. O código que itera sobre response.segments sem passar timestamp_granularities falhará. Verifique sempre a consistência entre os seus parâmetros de entrada e o tratamento da saída.
Combinações de parâmetros
Aqui estão as cinco combinações válidas que encontrará com mais frequência, da mais simples à mais especializada.
# Transcrição simples (apenas texto)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Com idioma forçado (sem marcas temporais)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Com marcas temporais por segmento
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Com diarização + marcas temporais
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Com enviesamento de contexto
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Uma restrição surpreendente no Voxtral 2 era que language e timestamp_granularities não podiam ser usados juntos na mesma chamada. A documentação do Voxtral 3 já não menciona esta restrição; verifique isto com um teste antes de confiar nisso.
Autenticação
Todos os pedidos exigem uma chave de API válida passada ao construtor do cliente. Em desenvolvimento, um argumento direto é suficiente. Em produção, utilize uma variável de ambiente para impedir que a chave acabe no seu repositório Git.
from mistralai.client import Mistral
# Via argumento direto
client = Mistral(api_key="your-api-key")
# Ou via variável de ambiente (recomendado para produção)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Pontos-chave
- O endpoint
/audio/transcriptionsé síncrono: envie o ficheiro, receba o texto. - Dois modos de carregamento: carregamento direto (
file) ou URL público (file_url). - Parâmetros opcionais:
language,timestamp_granularities,diarize,context_bias. - No Voxtral 2,
languageetimestamp_granularitieseram mutuamente exclusivos; a documentação do Voxtral 3 já não afirma isto. - Os formatos de áudio comuns são suportados; o limite é a janela de contexto partilhada entre o áudio e
context_bias(erro 400 se excedido). - A diarização e as marcas temporais podem ser combinadas.