A sua primeira chamada de transcrição
Nesta página
Curso atualizado em 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 removidos 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 é possível em tempo real, as definições da sessão em tempo real ficam bloqueadas após o primeiro bloco de áudio e as entradascontext_biassão de formato livre (frases com espaços). Fontes: Migrate from Voxtral 2 · Speech to Text.
A sua primeira transcrição com o Voxtral
Chega de teoria. Nesta lição, vai efetuar a sua primeira chamada completa à API de transcrição offline: um ficheiro de áudio local é enviado para o Voxtral Mini Transcribe 3 e processa o texto devolvido. O código cabe em poucas linhas, mas vamos depois evoluir para uma versão robusta adequada para operação autónoma.
Preparar o ambiente
O SDK da Mistral instala-se com um único comando. O passo de verificação que se segue poupa-o de procurar mais tarde um erro de importação.
# Instalar o SDK da Mistral
pip install mistralai
# Verificar a instalação
python -c "from mistralai.client import Mistral; print('SDK installed')"
Vai precisar de uma chave de API da Mistral. Crie uma em console.mistral.ai e guarde-a numa variável de ambiente em vez de a codificar diretamente no código:
export MISTRAL_API_KEY="your-api-key-here"
Transcrever um ficheiro local
Eis o código completo para transcrever um ficheiro de áudio local:
import os
from mistralai.client import Mistral
# Inicializar o cliente
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Abrir e transcrever o ficheiro de áudio
with open("mon_audio.mp3", "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "mon_audio.mp3"}
)
# Mostrar o resultado
print("=== Transcrição ===")
print(response.text)
É tudo. Em quatro linhas de código ativo, obtém a transcrição completa do seu ficheiro de áudio.
Vamos analisar estas quatro linhas. Mistral(api_key=...) cria o cliente com a sua chave de API; este é o objeto que vai reutilizar em todas as chamadas subsequentes. open("mon_audio.mp3", "rb") abre o ficheiro em modo binário, o que é obrigatório para áudio — omitir o b causa um erro de descodificação difícil de interpretar. O parâmetro file={"content": f, "file_name": "..."} espera um dicionário contendo o objeto do ficheiro e o seu nome; este nome não é decorativo, ajuda o servidor a detetar o formato. Por fim, response.text contém a transcrição completa como uma cadeia de caracteres.
Transcrever a partir de um URL
Se o seu ficheiro de áudio já estiver alojado online, utilize file_url em vez de file:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/mon_audio.mp3"
)
print(response.text)
O URL deve ser publicamente acessível. O servidor da Mistral vai descarregar o ficheiro diretamente, o que evita encaminhar o áudio através da sua máquina quando este já está na nuvem — uma poupança significativa de largura de banda para um catálogo de várias centenas de ficheiros.
Evoluir para uma versão robusta
O script mínimo funciona para um teste. Em produção, precisa de lidar com ficheiros em falta, formatos inesperados, chaves em falta e erros de rede. O script seguinte realiza estas verificações antes da chamada e guarda depois o resultado.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Transcreve um ficheiro de áudio com o Voxtral Mini Transcribe 3."""
# Verificar se o ficheiro existe
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")
# Verificar a extensão
extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
if fichier.suffix.lower() not in extensions_valides:
raise ValueError(
f"Format non supporté : {fichier.suffix}. "
f"Formats valides : {', '.join(extensions_valides)}"
)
# Verificar o tamanho (limite prático: ~200 MB)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")
# Inicializar o cliente
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
raise EnvironmentError("Variable MISTRAL_API_KEY non définie")
client = Mistral(api_key=api_key)
# Transcrever
try:
with open(chemin_fichier, "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": fichier.name}
)
return response.text
except Exception as e:
raise RuntimeError(f"Erreur de transcription : {e}")
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage : python transcrire.py <fichier_audio>")
sys.exit(1)
chemin = sys.argv[1]
print(f"Transcription de : {chemin}")
print("-" * 50)
texte = transcrire_audio(chemin)
print(texte)
# Guardar num ficheiro de texto
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Execute-o no terminal passando o caminho do ficheiro:
python transcribe.py meeting_march15.mp3
O script verifica o ficheiro, transcreve-o, mostra o resultado e guarda-o automaticamente num ficheiro .txt com o mesmo nome base. Tem agora a estrutura para processamento em lote: percorra um diretório e o seu arquivo de áudio torna-se num arquivo de texto pesquisável.
O que a resposta contém
O objeto response não se limita ao texto. Fornece também a duração do áudio processado e o idioma reconhecido pelo modelo — duas informações úteis para registar as suas tarefas e detetar ficheiros que não estejam no idioma esperado.
# Texto completo
print(response.text)
# Duração do áudio (em segundos)
print(f"Durée : {response.duration:.1f}s")
# Idioma detetado
print(f"Langue : {response.language}")
A melhor forma de avaliar a qualidade do modelo é testá-lo com a sua própria voz. Grave uma mensagem de voz com duração entre trinta segundos e dois minutos, execute o script acima e compare o resultado palavra por palavra com o que disse: verá imediatamente onde residem os raros erros, quase sempre em nomes próprios. Repita depois o exercício com um ficheiro noutro idioma, sem alterar o código, para observar a deteção automática de idioma em ação.
Pontos-chave
- A chamada mínima requer 4 linhas: cliente, abertura do ficheiro, chamada à API, leitura do resultado
- Dois modos de envio: ficheiro local (
file) ou URL (file_url) - O nome do ficheiro no dicionário
fileajuda na deteção do formato - Em produção, adicione tratamento de erros (ficheiro em falta, formato inválido, erro de rede)
response.textcontém sempre a transcrição completa como uma cadeia de caracteres