Transcrever um ficheiro de áudio: gpt-transcribe e Whisper
Nesta página
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 ogpt-transcribe. No entanto, ogpt-transcribenão fornece carimbos de tempo, legendas SRT ou VTT, nem uma respostaverbose_json. Para estas necessidades específicas, owhisper-1permanece a única opção até à sua descontinuação. O código anterior acedia aos segmentos como dicionários (segment["start"]), o que levanta umTypeErrorcom o SDK Python; são objetos (segment.start). Todas as chamadas foram verificadas com o SDKopenai3.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
| Modelo | Estado | Pontos-chave |
|---|---|---|
gpt-transcribe | Recomendado | Contexto (prompt), palavras-chave (keywords), idiomas esperados (languages), transcrição em streaming; 0,0045 $ por minuto |
whisper-1 | Obsoleto, 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-transcribe | Obsoleto, descontinuação a 26 de fevereiro de 2027 | Substituído por gpt-transcribe |
gpt-4o-transcribe-diarize | Obsoleto, descontinuação a 26 de fevereiro de 2027 | Identificaçã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)
promptdescreve o contexto numa única frase, no idioma da gravação. Não é uma instrução de sistema; é uma sugestão que orienta o reconhecimento.keywordslista termos a reconhecer. Introduza uma palavra-chave por item, sem<,>ou quebras de linha: a API rejeita todo o pedido se encontrar algum.languagesespecifica os idiomas esperados usando códigos ISO 639-1 (fr,en,es…). Substitui o parâmetrolanguagede 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-1egpt-4o-*-transcribesão descontinuados a 26 de fevereiro de 2027prompt,keywordselanguages(já nãolanguage) orientam o reconhecimento de termos e idiomasstream=Truedevolve a transcrição em tempo real (transcript.text.delta), sem uma sessão Realtime- Carimbos de tempo,
verbose_json, SRT e VTT existem apenas comwhisper-1até à 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