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

A sua primeira chamada de transcrição

Aula 5 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. A sua primeira transcrição com o Voxtral
  2. Preparar o ambiente
  3. Transcrever um ficheiro local
  4. Transcrever a partir de um URL
  5. Evoluir para uma versão robusta
  6. O que a resposta contém
  7. Pontos-chave

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 por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 e voxtral-mini-tts-3-0. Alterações principais: as marcas temporais são apenas por segmento (word devolve 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 entradas context_bias sã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 file ajuda na deteção do formato
  • Em produção, adicione tratamento de erros (ficheiro em falta, formato inválido, erro de rede)
  • response.text contém sempre a transcrição completa como uma cadeia de caracteres