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

Transcrever um ficheiro de áudio: gpt-transcribe e Whisper

Aula 6 de 18 Atualizada a 3 de novembro de 2026 Programador
Nesta página
  1. Transcrever uma gravação
  2. Qual o modelo em novembro de 2026
  3. Primeira transcrição
  4. Fornecer contexto ao modelo
  5. Acompanhar a transcrição em tempo real
  6. Carimbos de tempo e legendas: whisper-1, até 26 de fevereiro de 2027
  7. Ficheiros longos
  8. Pontos-chave

Lição reescrita a 3 de novembro de 2026. Este guia cobria anteriormente o whisper-1, que está obsoleto e será descontinuado a 26 de fevereiro de 2027. O guia de Transcrição de ficheiros da OpenAI recomenda agora o gpt-transcribe. No entanto, o gpt-transcribe não fornece carimbos de tempo, legendas SRT ou VTT, nem uma resposta verbose_json. Para estas necessidades específicas, o whisper-1 permanece a única opção até à sua descontinuação. O código anterior acedia aos segmentos como dicionários (segment["start"]), o que levanta um TypeError com o SDK Python; são objetos (segment.start). Todas as chamadas foram verificadas com o SDK openai 3.42.1. Fontes: File transcription · Create transcription · GPT-Transcribe · Deprecations.

Transcrever uma gravação

A transcrição de ficheiros aborda o caso de uso mais comum: tem uma gravação finalizada (uma reunião, um podcast, uma mensagem de voz) e precisa do texto. Envia o ficheiro para o endpoint /v1/audio/transcriptions e recebe a transcrição. Para áudio que ainda está a chegar, como de um microfone ou de uma chamada, a abordagem correta é a transcrição em tempo real através da Realtime API, abordada mais adiante neste curso.

O ficheiro deve ter 25 MB ou menos, num dos seguintes formatos: mp3, mp4, mpeg, mpga, m4a, wav ou webm.

Qual o modelo em novembro de 2026

ModeloEstadoPontos-chave
gpt-transcribeRecomendadoContexto (prompt), palavras-chave (keywords), idiomas esperados (languages), transcrição em streaming; 0,0045 $ por minuto
whisper-1Obsoleto, descontinuação a 26 de fevereiro de 2027Único modelo que fornece carimbos de tempo, verbose_json, SRT e VTT, e tradução para inglês
gpt-4o-transcribe, gpt-4o-mini-transcribeObsoleto, descontinuação a 26 de fevereiro de 2027Substituído por gpt-transcribe
gpt-4o-transcribe-diarizeObsoleto, descontinuação a 26 de fevereiro de 2027Identificação de oradores (diarized_json)

Primeira transcrição

from openai import OpenAI

client = OpenAI()

with open("recording.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
    )

print(transcription.text)

Por predefinição, a resposta é um objeto JSON: transcription.text contém o texto e transcription.languages lista os idiomas que o modelo reconheceu com confiança suficiente (uma lista vazia se não conseguir identificar nenhum).

Fornecer contexto ao modelo

Uma gravação de reunião está cheia de nomes próprios, acrónimos e termos internos que o modelo não tem razão para conhecer. O gpt-transcribe aceita três sugestões que pode combinar:

with open("meeting.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        prompt="Reunião de gestão sobre o projeto Corsen AI e o contrato AC-42.",
        keywords=["Corsen AI", "AC-42", "GDPR"],
        languages=["fr", "en"],
    )

print(transcription.text)
  • prompt descreve o contexto numa única frase, no idioma da gravação. Não é uma instrução de sistema; é uma sugestão que orienta o reconhecimento.
  • keywords lista termos a reconhecer. Introduza uma palavra-chave por item, sem <, > ou quebras de linha: a API rejeita todo o pedido se encontrar algum.
  • languages especifica os idiomas esperados usando códigos ISO 639-1 (fr, en, es…). Substitui o parâmetro language de modelos mais antigos: nunca envie ambos.

Acompanhar a transcrição em tempo real

Para ficheiros longos, não é necessário esperar até ao fim para exibir o início. Com stream=True, a API devolve eventos à medida que o processamento ocorre, sem exigir uma sessão Realtime:

with open("meeting.mp3", "rb") as audio_file:
    stream = client.audio.transcriptions.create(
        model="gpt-transcribe",
        file=audio_file,
        stream=True,
    )
    for event in stream:
        if event.type == "transcript.text.delta":
            print(event.delta, end="", flush=True)
        elif event.type == "transcript.text.done":
            print()  # transcrição completa em event.text

Carimbos de tempo e legendas: whisper-1, até 26 de fevereiro de 2027

O guia da OpenAI afirma explicitamente: os seus exemplos para carimbos de tempo ao nível da palavra, legendas e identificação de oradores dependem de modelos obsoletos. Se precisar destas funcionalidades, o whisper-1 permanece disponível até 26 de fevereiro de 2027 e é o único modelo que aceita verbose_json e timestamp_granularities:

with open("meeting.mp3", "rb") as audio_file:
    transcription = client.audio.transcriptions.create(
        model="whisper-1",
        file=audio_file,
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

for segment in transcription.segments or []:
    print(f"[{segment.start:.1f}s - {segment.end:.1f}s] {segment.text.strip()}")

Os segmentos são objetos do SDK: leia segment.start, não segment["start"]. Com timestamp_granularities=["word"], os carimbos de tempo ao nível da palavra aparecem em transcription.words, ao custo de uma latência ligeiramente superior. O mesmo modelo também produz legendas prontas a usar: com response_format="srt" ou "vtt", o SDK devolve diretamente o texto do ficheiro de legendas.

O guia ainda não designa um substituto para estas funções. Se o seu produto depende de carimbos de tempo ou legendas, planeie uma solução antes de 26 de fevereiro de 2027.

Ficheiros longos

Para ficheiros superiores a 25 MB, comprima o áudio ou divida-o. A documentação recomenda evitar cortes no meio de uma frase, o que perde contexto, e sugere a biblioteca pydub para divisão (a OpenAI não garante este software de terceiros). Passar o final do bloco anterior no prompt ajuda o modelo a manter a continuidade, um uso do parâmetro citado no guia:

from pydub import AudioSegment


def transcribe_long(path: str, duration_ms: int = 10 * 60 * 1000) -> str:
    """Transcreve uma gravação longa em blocos de 10 minutos."""
    audio = AudioSegment.from_file(path)
    texts: list[str] = []

    for i, start in enumerate(range(0, len(audio), duration_ms)):
        chunk = f"chunk_{i}.mp3"
        audio[start:start + duration_ms].export(chunk, format="mp3")
        options = {"prompt": texts[-1][-500:]} if texts else {}  # continuidade
        with open(chunk, "rb") as f:
            result = client.audio.transcriptions.create(model="gpt-transcribe", file=f, **options)
        texts.append(result.text)

    return " ".join(texts)

A divisão por duração fixa corta por vezes uma frase ao meio: para um resultado polido, divida em vez disso no silêncio.

Pontos-chave

  • gpt-transcribe é o modelo recomendado para transcrição de ficheiros; whisper-1 e gpt-4o-*-transcribe são descontinuados a 26 de fevereiro de 2027
  • prompt, keywords e languages (já não language) orientam o reconhecimento de termos e idiomas
  • stream=True devolve a transcrição em tempo real (transcript.text.delta), sem uma sessão Realtime
  • Carimbos de tempo, verbose_json, SRT e VTT existem apenas com whisper-1 até à sua descontinuação; leia os segmentos como objetos (segment.start)
  • Máximo de 25 MB por ficheiro: comprima ou divida, de preferência no silêncio