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

A API de Transcrição Offline

Aula 4 de 16 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. O endpoint de transcrição
  2. Parâmetros da chamada
  3. Formatos de áudio suportados
  4. Estrutura da resposta
  5. Combinações de parâmetros
  6. Autenticação
  7. Pontos-chave

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 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 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 de context_bias sã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".
  • file ou file_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.

FormatoCaracterística
MP3Mais comum, boa compressão
WAVSem compressão, qualidade máxima
FLACCompressão sem perdas
OGGFormato aberto, boa compressão
M4A / AACFormato Apple, comum em telemóveis
WEBMFormato 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, language e timestamp_granularities eram 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.