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 maior precisão,gpt-4o-mini-transcribepara economia de custos,whisper-1para timestamps/SRT/VTT, ougpt-4o-transcribe-diarizepara identificação de falantes. Os arquivos devem ter menos de 25 MB – fragmente arquivos maiores. Usepromptpara guiar vocabulário e estilo. 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/saída SRT/VTT, gpt-4o-transcribe-diarize para rótulos de falantes)
(Você DEVE fragmentar 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últiplos falantes (diarização)
- Transcrever em streaming de forma progressiva enquanto 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, siglas e estilo
- Fragmentaçã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 a 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 que não sejam OpenAI – use um SDK de fala agnóstico a provedores
Índice de Exemplos
- Principal: Transcrição, Tradução, Timestamps, Fragmentação, 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 vários modelos otimizados para diferentes necessidades. A API é simples – você envia um arquivo de áudio e recebe texto de volta – mas escolher o modelo, formato de resposta e parâmetros corretos é crítico para obter 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 fragmentar áudios longos. Divida nos limites das frases para preservar o contexto.
- O prompting melhora a precisão – O parâmetro
promptguia vocabulário, siglas e estilo de formatação. Ele não dá instruções – fornece contexto que o modelo utiliza para 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 que não seja 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 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
+-- Custo-eficiente, 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
| Funcionalidade | 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 de idioma | 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, siglas e estilo de formatação. Não o use para dar instruções como "por favor, transcreva com cuidado" – ele corresponde ao estilo e 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: Siglas/nomes próprios, preservar contexto entre fragmentos (passar 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: Fragmentação de Arquivos Grandes
Arquivos de áudio que excedem 25 MB devem ser divididos antes da transcrição. Divida nos limites das frases (ex.: via ffmpeg) para preservar o contexto. Passe o final da transcrição anterior como prompt para continuidade entre fragmentos.
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, transcrever sequencialmente, passando o contexto anterior via prompt
Veja core.md para a implementação completa de fragmentação com validação de tamanho e preservação de contexto.
Padrão 5: Transcrição em Streaming
Transcreva resultados parciais em streaming enquanto 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 logprobs.
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(). 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 automaticamente o idioma)
+-- 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 (API retorna erro)
- Usar
gpt-4o-transcribe-diarizesemchunking_strategyem áudio > 30 segundos (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ê deseja transcrição no mesmo idioma (a tradução sempre gera inglês) - Dividir o áudio no meio de uma frase ao fragmentar (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 do fragmento anterior ao transcrever arquivos divididos (reduz a precisão nos limites)
Pegadinhas e Casos Extremos:
- O parâmetro
prompté limitado a aproximadamente 224 tokens nowhisper-1. Prompts mais longos são truncados. whisper-1pode alucinar texto para segmentos de áudio silenciosos ou quase silenciosos. Useno_speech_probdoverbose_jsonpara detectar isso.gpt-4o-transcribeegpt-4o-mini-transcribesuportam apenas os formatos de respostajsonetext– nãosrt,vttouverbose_json.- O parâmetro
languageusa códigos ISO 639-1 (ex.:"en","fr","ja"). Definir isso 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.
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 suporta apenas
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]