Patrones de OpenAI Whisper
Guía rápida: Usa
client.audio.transcriptions.create()para voz a texto yclient.audio.translations.create()para audio no inglés a texto en inglés. Eligegpt-4o-transcribepara máxima precisión,gpt-4o-mini-transcribepara eficiencia de costos,whisper-1para marcas de tiempo/SRT/VTT, ogpt-4o-transcribe-diarizepara identificación de hablantes. Los archivos deben tener menos de 25 MB; fragmenta archivos más grandes. Usapromptpara guiar el vocabulario y el estilo. La transmisión en streaming está disponible mediantestream: truepara salida progresiva en modelosgpt-4o-transcribe.
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo el código debe seguir las convenciones del proyecto en CLAUDE.md (kebab-case, exportaciones nombradas, orden de importaciones,
import type, constantes nombradas)
(DEBES elegir el modelo correcto para el caso de uso: gpt-4o-transcribe para precisión, whisper-1 para marcas de tiempo/salida SRT/VTT, gpt-4o-transcribe-diarize para etiquetas de hablante)
(DEBES fragmentar archivos de audio mayores de 25 MB antes de enviarlos a la API; la API rechaza archivos que excedan este límite)
(DEBES pasar response_format: "verbose_json" al usar timestamp_granularities; las marcas de tiempo solo funcionan con este formato en whisper-1)
(DEBES establecer chunking_strategy: "auto" al usar gpt-4o-transcribe-diarize con audio de más de 30 segundos; la API lo requiere)
</critical_requirements>
Detección automática: Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcripción, voz a texto, diarización, diarized_json, timestamp_granularities, verbose_json
Cuándo usarlo:
- Transcribir archivos de audio (reuniones, entrevistas, podcasts, notas de voz) a texto
- Traducir audio no inglés a texto en inglés
- Generar subtítulos en formato SRT o VTT a partir de audio
- Obtener marcas de tiempo a nivel de palabra o segmento para edición de video
- Identificar hablantes en audio con múltiples interlocutores (diarización)
- Transmitir resultados de transcripción de forma progresiva mientras el modelo procesa el audio
Patrones clave cubiertos:
- Selección de modelo (whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
- Formatos de respuesta (json, text, srt, vtt, verbose_json, diarized_json)
- Marcas de tiempo (a nivel de palabra, a nivel de segmento) y generación de subtítulos
- Indicaciones para vocabulario, acrónimos y estilo
- Fragmentación de archivos grandes (> 25 MB) con preservación de contexto
- Transcripción en streaming con
stream: true - Traducción al inglés mediante
audio.translations.create() - Diarización de hablantes con referencias a hablantes
Cuándo NO usarlo:
- Texto a voz (TTS): usa la API TTS de OpenAI (
client.audio.speech.create()) - Conversaciones de voz bidireccionales en tiempo real: usa la API Realtime de OpenAI
- Transcripción con proveedores que no sean OpenAI: usa un SDK de voz agnóstico al proveedor
Índice de Ejemplos
- Núcleo: Transcripción, Traducción, Marcas de Tiempo, Fragmentación, Streaming, Diarización -- Todos los patrones de la API de Audio
Filosofía
La API de Audio de OpenAI proporciona transcripción de voz a texto y traducción a través de múltiples modelos optimizados para diferentes necesidades. La API es simple: envías un archivo de audio y recibes texto, pero elegir el modelo, formato de respuesta y parámetros correctos es crítico para obtener resultados de calidad.
Principios fundamentales:
- La selección del modelo es importante --
gpt-4o-transcribeproduce la mayor precisión con tasas de alucinación más bajas.whisper-1es el único modelo que admite SRT/VTT/verbose_json con marcas de tiempo.gpt-4o-transcribe-diarizeagrega identificación de hablantes. - El tamaño del archivo es la principal limitación -- el límite de 25 MB significa que debes fragmentar el audio más largo. Divide en los límites de las oraciones para preservar el contexto.
- Las indicaciones mejoran la precisión -- El parámetro
promptguía el vocabulario, los acrónimos y el formato de estilo. No da instrucciones, sino que proporciona contexto con el que el modelo compara. - El formato de respuesta determina las funciones disponibles -- Las marcas de tiempo requieren
verbose_jsonenwhisper-1. La diarización requierediarized_json. SRT/VTT solo están disponibles enwhisper-1.
Cuándo usar la API de Audio:
- Necesitas una transcripción precisa de archivos de audio grabados
- Necesitas subtítulos (SRT/VTT) a partir de audio
- Necesitas identificar quién habla en una conversación
- Necesitas traducir voz no inglesa a texto en inglés
Cuándo NO usarlo:
- Chat de voz en tiempo real: usa la API Realtime
- Texto a voz: usa
client.audio.speech.create() - Necesitas transcripción en un idioma de destino que no sea inglés (la traducción solo produce inglés)
Patrones Principales
Patrón 1: Transcripción Básica
Envía un archivo de audio y recibe texto. El modelo detecta automáticamente el idioma.
const transcription = await client.audio.transcriptions.create({
model: "gpt-4o-transcribe",
file: createReadStream(audioPath),
});
Usa gpt-4o-transcribe para la máxima precisión. No uses whisper-1 con verbose_json cuando solo necesites texto plano: agrega sobrecarga y tiene tasas de alucinación más altas. Consulta core.md para ver ejemplos completos.
Patrón 2: Selección de Modelo
Cada modelo tiene capacidades y compensaciones distintas.
¿Qué necesitas?
+-- Máxima precisión, texto plano -> gpt-4o-transcribe
+-- Económico, texto plano -> gpt-4o-mini-transcribe
+-- Marcas de tiempo (palabra/segmento) -> whisper-1 (verbose_json)
+-- Subtítulos SRT o VTT -> whisper-1 (formato srt/vtt)
+-- Identificación de hablantes -> gpt-4o-transcribe-diarize
+-- Salida en streaming -> gpt-4o-transcribe o gpt-4o-mini-transcribe
Matriz de Capacidades del Modelo
| Característica | whisper-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| Formatos de respuesta | json, text, srt, vtt, verbose_json | json, text | json, text | json, text, diarized_json |
| Marcas de tiempo | palabra + segmento | No | No | No |
| Streaming | No | Sí | Sí | No |
| Soporte de prompt | Sí (224 tokens) | Sí | Sí | No |
| Logprobs | No | Sí | Sí | No |
| Etiquetas de hablante | No | No | No | Sí |
| Parámetro de idioma | Sí | Sí | Sí | Sí |
Patrón 3: Indicaciones para Vocabulario y Estilo
El parámetro prompt proporciona contexto, no instrucciones. Guía la ortografía de nombres, acrónimos y el formato de estilo. No lo uses para dar instrucciones como "transcribe cuidadosamente", sino que coincide con el contexto de estilo y vocabulario.
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/nombres propios, preservar el contexto entre fragmentos (pasar la cola de la transcripción anterior), mantener las muletillas, guía de estilo de escritura. Consulta core.md para ver ejemplos detallados de vocabulario.
Patrón 4: Fragmentación de Archivos Grandes
Los archivos de audio que superen los 25 MB deben dividirse antes de la transcripción. Divide en los límites de las oraciones (por ejemplo, con ffmpeg) para preservar el contexto. Pasa la cola de la transcripción anterior como prompt para la continuidad entre fragmentos.
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 MB
// Dividir con ffmpeg: ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Luego transcribir secuencialmente, pasando el contexto anterior a través de prompt
Consulta core.md para ver la implementación completa de fragmentación con validación de tamaño y preservación de contexto.
Patrón 5: Transcripción en Streaming
Transmite resultados de transcripción parciales mientras el modelo procesa el audio. Solo gpt-4o-transcribe y gpt-4o-mini-transcribe admiten stream: true. Escucha eventos transcript.text.delta para salida progresiva y transcript.text.done para la finalización. NO uses stream: true con whisper-1; no es compatible.
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);
}
Consulta core.md para ver ejemplos completos de streaming y logprob.
Patrón 6: Traducción al Inglés
Traduce audio no inglés a texto en inglés. Solo whisper-1 es compatible mediante audio.translations.create(). Para transcripción en el mismo idioma, usa audio.transcriptions.create(). La traducción solo produce inglés; no hay forma de traducir a otros idiomas.
const translation = await client.audio.translations.create({
model: "whisper-1",
file: createReadStream(audioPath),
});
Consulta core.md para ver ejemplos completos de traducción, incluyendo indicaciones de vocabulario.
Patrón 7: Diarización de Hablantes
Identifica quién habla en audio con múltiples interlocutores. Usa gpt-4o-transcribe-diarize con response_format: "diarized_json" y chunking_strategy: "auto" (necesario para audio > 30s). La diarización no admite prompt, logprobs ni 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, proporciona known_speaker_names y known_speaker_references (clips de audio de 2 a 10 segundos como URL de datos) para asignar segmentos a hablantes conocidos (hasta 4). Consulta core.md para ver ejemplos completos de diarización.
<decision_framework>
Marco de Decisión
Qué Modelo Elegir
¿Qué necesitas de la transcripción?
+-- Solo texto (máxima precisión) -> gpt-4o-transcribe
+-- Solo texto (sensible al costo) -> gpt-4o-mini-transcribe
+-- Marcas de tiempo de palabra/segmento -> whisper-1 (verbose_json)
+-- Archivos de subtítulos SRT o VTT -> whisper-1 (srt o vtt)
+-- Identificación de hablantes -> gpt-4o-transcribe-diarize
+-- Salida progresiva/streaming -> gpt-4o-transcribe (stream: true)
Qué Formato de Respuesta Usar
¿Qué salida necesitas?
+-- Cadena de texto plano -> "text"
+-- JSON con campo de texto -> "json" (predeterminado)
+-- Subtítulos para video -> "srt" o "vtt" (solo whisper-1)
+-- Marcas de tiempo (palabra/segmento) -> "verbose_json" (solo whisper-1)
+-- Segmentos etiquetados por hablante -> "diarized_json" (solo gpt-4o-transcribe-diarize)
Transcripción vs Traducción
¿El audio está en inglés?
+-- SÍ -> Usa audio.transcriptions.create()
+-- NO -> ¿Quieres la salida en el idioma original?
+-- SÍ -> Usa audio.transcriptions.create() (detecta el idioma automáticamente)
+-- NO (quieres inglés) -> Usa audio.translations.create() (solo whisper-1)
</decision_framework>
<red_flags>
BANDERAS ROJAS
Problemas de Alta Prioridad:
- Usar
timestamp_granularitiessinresponse_format: "verbose_json"enwhisper-1(se ignora silenciosamente) - Enviar archivos de más de 25 MB (la API devuelve un error)
- Usar
gpt-4o-transcribe-diarizesinchunking_strategyen audio de más de 30 segundos (la API devuelve un error) - Usar
stream: trueconwhisper-1(no compatible)
Problemas de Prioridad Media:
- Usar
whisper-1cuandogpt-4o-transcribeproduciría mayor precisión (whisper-1 tiene tasas de alucinación más altas) - No pasar el parámetro
languagecuando conoces el idioma (la detección automática puede ser incorrecta para audio corto o ruidoso) - Usar
audio.translations.create()cuando quieres transcripción en el mismo idioma (la traducción siempre produce inglés) - Dividir el audio en medio de una oración al fragmentar (pierde contexto en los límites)
Errores Comunes:
- Tratar el parámetro
promptcomo una instrucción ("transcribe cuidadosamente"): es contexto para la coincidencia de vocabulario y estilo - Usar
gpt-4o-transcribecuando necesitas salida SRT/VTT: solowhisper-1admite esos formatos - Esperar que
gpt-4o-transcribe-diarizeadmita prompts o logprobs (no los admite) - Usar el endpoint de traducción para audio en inglés (solo traduce de no inglés a inglés)
- No proporcionar el contexto del fragmento anterior al transcribir archivos divididos (reduce la precisión en los límites)
Casos Especiales y Curiosidades:
- El parámetro
promptestá limitado a aproximadamente 224 tokens enwhisper-1. Los prompts más largos se truncan. whisper-1puede alucinar texto para segmentos de audio silenciosos o casi silenciosos. Usano_speech_probdeverbose_jsonpara detectarlo.gpt-4o-transcribeygpt-4o-mini-transcribesolo admiten formatos de respuestajsonytext, nosrt,vttniverbose_json.- El parámetro
languageusa códigos ISO 639-1 (por ejemplo,"en","fr","ja"). Configurarlo mejora la precisión para audio corto. - Formatos de archivo compatibles: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Otros formatos deben convertirse primero.
gpt-4o-transcribe-diarizeetiqueta a los hablantes como "A", "B", "C" a menos que proporcionesknown_speaker_namesyknown_speaker_referencescon clips de audio cortos.- El endpoint de traducción solo admite
whisper-1y solo produce inglés; no hay forma de traducir a otros idiomas a través de esta API. - La transcripción en streaming emite eventos
transcript.text.deltacon una propiedad de cadenadelta, además de un evento finaltranscript.text.done.
</red_flags>
<critical_reminders>
RECORDATORIOS CRÍTICOS
**
…
[truncado para la traducción]