Padrões OpenAI Whisper
Guia Rápido: Use
client.audio.transcriptions.create()para fala para texto eclient.audio.translations.create()para áudio não-inglês para texto em inglês. Escolhagpt-4o-transcribepara a maior precisão,gpt-4o-mini-transcribepara economia de custos,whisper-1para timestamps/SRT/VTT, ougpt-4o-transcribe-diarizepara identificação de falantes. Arquivos devem ter menos de 25 MB — divida arquivos maiores em partes. Usepromptpara guiar vocabulário e estilo. O streaming está disponível viastream: truepara saída progressiva nos modelosgpt-4o-transcribe.
<critical_requirements>
CRÍTICO: Antes de Usar Esta Skill
Todo código deve seguir as convenções do projeto em CLAUDE.md (kebab-case, exports nomeados, ordenação de imports,
import type, constantes nomeadas)
(Você DEVE escolher o modelo correto para o caso de uso — gpt-4o-transcribe para precisão, whisper-1 para timestamps/SRT/VTT, gpt-4o-transcribe-diarize para rótulos de falantes)
(Você DEVE dividir arquivos de áudio maiores que 25 MB antes de enviar para a API — a API rejeita arquivos que excedem este limite)
(Você DEVE passar response_format: "verbose_json" ao usar timestamp_granularities — timestamps só funcionam com este formato no whisper-1)
(Você DEVE definir chunking_strategy: "auto" ao usar gpt-4o-transcribe-diarize com áudio com mais de 30 segundos — a API exige isso)
</critical_requirements>
Detecção automática: Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, speech-to-text, diarization, diarized_json, timestamp_granularities, verbose_json
Quando usar:
- Transcrever arquivos de áudio (reuniões, entrevistas, podcasts, notas de voz) para texto
- Traduzir áudio não-inglês para texto em inglês
- Gerar legendas no formato SRT ou VTT a partir de áudio
- Obter timestamps em nível de palavra ou segmento para edição de vídeo
- Identificar falantes em áudio com múltiplas vozes (diarização)
- Resultados de transcrição em streaming progressivo conforme o modelo processa o áudio
Principais padrões abordados:
- Seleção de modelo (whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
- Formatos de resposta (json, text, srt, vtt, verbose_json, diarized_json)
- Timestamps (nível de palavra, nível de segmento) e geração de legendas
- Prompting para vocabulário, acrônimos e estilo
- Divisão de arquivos grandes (> 25 MB) com preservação de contexto
- Transcrição em streaming com
stream: true - Tradução para inglês via
audio.translations.create() - Diarização de falantes com referências de falantes
Quando NÃO usar:
- Texto para fala (TTS) — use a API TTS da OpenAI (
client.audio.speech.create()) - Conversas de voz bidirecionais em tempo real — use a API Realtime da OpenAI
- Transcrição com provedores não-OpenAI — use um SDK de fala agnóstico a provedores
Índice de Exemplos
- Core: Transcrição, Tradução, Timestamps, Chunking, Streaming, Diarização — Todos os padrões da API de Áudio
Filosofia
A API de Áudio da OpenAI fornece transcrição de fala para texto e tradução através de múltiplos modelos otimizados para diferentes necessidades. A API é simples — você envia um arquivo de áudio e recebe o texto de volta — mas escolher o modelo, formato de resposta e parâmetros corretos é crítico para resultados de qualidade.
Princípios fundamentais:
- A seleção do modelo importa —
gpt-4o-transcribeproduz a maior precisão com menores taxas de alucinação.whisper-1é o único modelo que suporta SRT/VTT/verbose_json com timestamps.gpt-4o-transcribe-diarizeadiciona identificação de falantes. - O tamanho do arquivo é a principal restrição — o limite de 25 MB significa que você deve dividir áudios mais longos. Divida nos limites das frases para preservar o contexto.
- O prompting melhora a precisão — O parâmetro
promptguia vocabulário, acrônimos e estilo de formatação. Ele não dá instruções — fornece contexto contra o qual o modelo faz correspondência. - O formato de resposta determina os recursos disponíveis — Timestamps exigem
verbose_jsonnowhisper-1. Diarização exigediarized_json. SRT/VTT estão disponíveis apenas nowhisper-1.
Quando usar a API de Áudio:
- Você precisa de transcrição precisa de arquivos de áudio gravados
- Você precisa de legendas (SRT/VTT) a partir de áudio
- Você precisa identificar quem está falando em uma conversa
- Você precisa traduzir fala não-inglesa para texto em inglês
Quando NÃO usar:
- Chat de voz em tempo real — use a API Realtime
- Texto para fala — use
client.audio.speech.create() - Você precisa de transcrição em um idioma de destino não-inglês (a tradução só gera inglês)
Padrões Principais
Padrão 1: Transcrição Básica
Envie um arquivo de áudio e receba o texto de volta. O modelo detecta automaticamente o idioma.
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
});
Use gpt-4o-transcribe para a maior precisão. Não use whisper-1 com verbose_json quando você só precisa de texto simples — isso adiciona sobrecarga e tem taxas de alucinação mais altas. Veja core.md para exemplos completos.
Padrão 2: Seleção de Modelo
Cada modelo tem capacidades e trade-offs distintos.
O que você precisa?
+-- Maior precisão, texto simples -> gpt-4o-transcribe
+-- Econômico, texto simples -> gpt-4o-mini-transcribe
+-- Timestamps (palavra/segmento) -> whisper-1 (verbose_json)
+-- Legendas SRT ou VTT -> whisper-1 (formato srt/vtt)
+-- Identificação de falantes -> gpt-4o-transcribe-diarize
+-- Saída em streaming -> gpt-4o-transcribe ou gpt-4o-mini-transcribe
Matriz de Capacidades dos Modelos
| Recurso | whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| Formatos de resposta | json, text, srt, vtt, verbose_json | json, text | json, text | json, text, diarized_json |
| Timestamps | palavra + segmento | Não | Não | Não |
| Streaming | Não | Sim | Sim | Não |
| Suporte a prompt | Sim (224 tokens) | Sim | Sim | Não |
| Logprobs | Não | Sim | Sim | Não |
| Rótulos de falantes | Não | Não | Não | Sim |
| Parâmetro language | Sim | Sim | Sim | Sim |
Padrão 3: Prompting para Vocabulário e Estilo
O parâmetro prompt fornece contexto — não instruções. Ele guia a grafia de nomes, acrônimos e estilo de formatação. Não o use para dar instruções como "por favor, transcreva com cuidado" — ele corresponde ao estilo e ao contexto do vocabulário.
const VOCABULARY_PROMPT = "Kubernetes, kubectl, etcd, NGINX, gRPC, PostgreSQL";
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
prompt: VOCABULARY_PROMPT,
});
Casos de uso: Acrônimos/nomes próprios, preservar contexto entre partes (passe o final da transcrição anterior), manter palavras de preenchimento, orientação de estilo de escrita. Veja core.md para exemplos detalhados de vocabulário.
Padrão 4: Divisão de Arquivos Grandes
Arquivos de áudio que excedem 25 MB devem ser divididos antes da transcrição. Divida nos limites das frases (por exemplo, via ffmpeg) para preservar o contexto. Passe o final da transcrição anterior como prompt para continuidade entre as partes.
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// Dividir com ffmpeg: ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Em seguida, transcreva sequencialmente, passando o contexto anterior via prompt
Veja core.md para a implementação completa de chunking com validação de tamanho e preservação de contexto.
Padrão 5: Transcrição em Streaming
Transmita resultados parciais de transcrição à medida que o modelo processa o áudio. Apenas gpt-4o-transcribe e gpt-4o-mini-transcribe suportam stream: true. Escute eventos transcript.text.delta para saída progressiva e transcript.text.done para conclusão. NÃO use stream: true com whisper-1 — não é suportado.
const stream = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
stream: true,
});
for await (const event of stream) {
if (event.type === "transcript.text.delta") process.stdout.write(event.delta);
}
Veja core.md para exemplos completos de streaming e logprob.
Padrão 6: Tradução para Inglês
Traduza áudio não-inglês para texto em inglês. Apenas whisper-1 é suportado via audio.translations.create(). Para transcrição no mesmo idioma, use audio.transcriptions.create() em vez disso. A tradução só gera inglês — não há como traduzir para outros idiomas.
const translation = await client.audio.translations.create({
model: "whisper-1",
file: createReadStream(audioPath),
});
Veja core.md para exemplos completos de tradução, incluindo prompting de vocabulário.
Padrão 7: Diarização de Falantes
Identifique quem está falando em áudio com múltiplos falantes. Use gpt-4o-transcribe-diarize com response_format: "diarized_json" e chunking_strategy: "auto" (obrigatório para áudio > 30s). A diarização não suporta prompt, logprobs ou timestamp_granularities.
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe-diarize",
file: createReadStream(audioPath),
response_format: "diarized_json",
chunking_strategy: "auto",
});
Opcionalmente, forneça known_speaker_names e known_speaker_references (clipes de áudio de 2 a 10 segundos como URLs de dados) para mapear segmentos para falantes conhecidos (até 4). Veja core.md para exemplos completos de diarização.
<decision_framework>
Estrutura de Decisão
Qual Modelo Escolher
O que você precisa da transcrição?
+-- Apenas texto (maior precisão) -> gpt-4o-transcribe
+-- Apenas texto (sensível a custo) -> gpt-4o-mini-transcribe
+-- Timestamps de palavra/segmento -> whisper-1 (verbose_json)
+-- Arquivos de legenda SRT ou VTT -> whisper-1 (srt ou vtt)
+-- Identificação de falantes -> gpt-4o-transcribe-diarize
+-- Saída progressiva/streaming -> gpt-4o-transcribe (stream: true)
Qual Formato de Resposta Usar
Qual saída você precisa?
+-- String de texto simples -> "text"
+-- JSON com campo text -> "json" (padrão)
+-- Legendas para vídeo -> "srt" ou "vtt" (apenas whisper-1)
+-- Timestamps (palavra/segmento) -> "verbose_json" (apenas whisper-1)
+-- Segmentos com rótulos de falantes -> "diarized_json" (apenas gpt-4o-transcribe-diarize)
Transcrição vs Tradução
O áudio está em inglês?
+-- SIM -> Use audio.transcriptions.create()
+-- NÃO -> Você quer a saída no idioma original?
+-- SIM -> Use audio.transcriptions.create() (detecta idioma automaticamente)
+-- NÃO (quer inglês) -> Use audio.translations.create() (apenas whisper-1)
</decision_framework>
<red_flags>
BANDEIRAS VERMELHAS
Problemas de Alta Prioridade:
- Usar
timestamp_granularitiessemresponse_format: "verbose_json"nowhisper-1(ignorado silenciosamente) - Enviar arquivos maiores que 25 MB (a API retorna erro)
- Usar
gpt-4o-transcribe-diarizesemchunking_strategyem áudio com mais de 30 segundos (a API retorna erro) - Usar
stream: truecomwhisper-1(não suportado)
Problemas de Média Prioridade:
- Usar
whisper-1quandogpt-4o-transcribeproduziria maior precisão (whisper-1 tem taxas de alucinação mais altas) - Não passar o parâmetro
languagequando você conhece o idioma (a detecção automática pode estar errada para áudio curto ou ruidoso) - Usar
audio.translations.create()quando você quer transcrição no mesmo idioma (a tradução sempre gera inglês) - Dividir o áudio no meio de uma frase ao fazer chunking (perde contexto nos limites)
Erros Comuns:
- Tratar o parâmetro
promptcomo uma instrução ("por favor, transcreva com cuidado") — ele é contexto para correspondência de vocabulário e estilo - Usar
gpt-4o-transcribequando você precisa de saída SRT/VTT — apenaswhisper-1suporta esses formatos - Esperar que
gpt-4o-transcribe-diarizesuporte prompts ou logprobs (não suporta) - Usar o endpoint de tradução para áudio em inglês (ele só traduz não-inglês para inglês)
- Não fornecer contexto da parte anterior ao transcrever arquivos divididos (reduz a precisão nos limites)
Armadilhas e Casos de Borda:
- O parâmetro
prompté limitado a aproximadamente 224 tokens nowhisper-1. Prompts mais longos são truncados. - O
whisper-1pode alucinar texto para segmentos de áudio silenciosos ou quase silenciosos. Useno_speech_probdoverbose_jsonpara detectar isso. gpt-4o-transcribeegpt-4o-mini-transcribesó suportam formatos de respostajsonetext— nãosrt,vttouverbose_json.- O parâmetro
languageusa códigos ISO 639-1 (por exemplo,"en","fr","ja"). Configurá-lo melhora a precisão para áudio curto. - Formatos de arquivo suportados: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Outros formatos devem ser convertidos primeiro.
- O
gpt-4o-transcribe-diarizerotula falantes como "A", "B", "C" a menos que você forneçaknown_speaker_nameseknown_speaker_referencescom clipes de áudio curtos. - O endpoint de tradução só suporta
whisper-1e só gera inglês — não há como traduzir para outros idiomas através desta API. - A transcrição em streaming emite eventos
transcript.text.deltacom uma propriedade de stringdelta, além de um evento finaltranscript.text.done.
</red_flags>
<critical_reminders>
LEMBRETES CRÍTICOS
**
…
[truncado para tradução]