Patrones de OpenAI Whisper
Guía rápida: Usa
client.audio.transcriptions.create()para convertir voz a texto yclient.audio.translations.create()para traducir audio que no esté en inglés a texto en inglés. Eligegpt-4o-transcribepara la máxima precisión,gpt-4o-mini-transcribepara eficiencia de costes,whisper-1para marcas de tiempo/SRT/VTT, ogpt-4o-transcribe-diarizepara identificar al hablante. Los archivos deben tener un tamaño inferior a 25 MB; fragmenta archivos más grandes. Usapromptpara guiar el vocabulario y el estilo. La transmisión en streaming está disponible mediantestream: truepara obtener resultados progresivos con los modelosgpt-4o-transcribe.
<critical_requirements>
CRÍTICO: Antes de Usar Este Skill
Todo el código debe seguir las convenciones del proyecto indicadas en CLAUDE.md (kebab-case, exportaciones con nombre, orden de importaciones,
import type, constantes con nombre)
(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 los archivos de audio de más de 25 MB antes de enviarlos a la API; la API rechaza los archivos que superan 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, transcription, speech-to-text, diarization, diarized_json, timestamp_granularities, verbose_json
Cuándo usarlo:
- Transcribir archivos de audio (reuniones, entrevistas, podcasts, notas de voz) a texto
- Traducir audio que no esté en 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 de segmento para edición de vídeo
- Identificar a los hablantes en audio con varios 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
- Uso de
promptpara vocabulario, acrónimos y estilo - Fragmentación de archivos grandes (> 25 MB) con preservación del contexto
- Transcripción en streaming con
stream: true - Traducción al inglés mediante
audio.translations.create() - Diarización de hablantes con referencias a los mismos
Cuándo NO usarlo:
- Conversión de texto a voz (TTS): usa la API de TTS de OpenAI (
client.audio.speech.create()) - Conversaciones de voz bidireccionales en tiempo real: usa la API en Tiempo Real 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. Sin embargo, elegir el modelo, el formato de respuesta y los parámetros correctos es fundamental para obtener resultados de calidad.
Principios fundamentales:
- La selección del modelo importa:
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-diarizeañade la identificación del hablante. - 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.
- El uso de
promptmejora la precisión: el parámetropromptguía el vocabulario, los acrónimos y el estilo de formato. No da instrucciones, sino que proporciona un contexto que el modelo utiliza como referencia. - 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 audio que no esté en inglés a texto en inglés
Cuándo NO usarlo:
- Chat de voz en tiempo real: usa la API en Tiempo Real
- Conversión de texto a voz: usa
client.audio.speech.create() - Necesitas transcripción a un idioma de destino que no sea inglés (la traducción solo genera texto en inglés)
Patrones Principales
Patrón 1: Transcripción Básica
Envía un archivo de audio y recibe el 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 obtener la máxima precisión. No uses whisper-1 con verbose_json cuando solo necesites texto plano; añade 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 ventajas/desventajas distintas.
¿Qué necesitas?
+-- Máxima precisión, texto plano -> gpt-4o-transcribe
+-- Eficiencia de costes, 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 del hablante -> 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: Uso de Prompt para Vocabulario y Estilo
El parámetro prompt proporciona contexto, no instrucciones. Guía la ortografía de nombres, acrónimos y el estilo de formato. No lo uses para dar instrucciones como "transcribe con cuidado", sino para proporcionar 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, preservación del contexto entre fragmentos (pasar el final de la transcripción anterior), mantener palabras de relleno, 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 el final de la transcripción anterior como prompt para mantener 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 transcribe secuencialmente, pasando el contexto anterior mediante prompt
Consulta core.md para ver la implementación completa de fragmentación con validación de tamaño y preservación del 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 los eventos transcript.text.delta para obtener la salida progresiva y transcript.text.done para la finalización. NO uses stream: true con whisper-1, ya que 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 logprobs.
Patrón 6: Traducción al Inglés
Traduce audio que no esté en inglés a texto en inglés. Solo se admite whisper-1 a través de audio.translations.create(). Para transcripción en el mismo idioma, usa audio.transcriptions.create(). La traducción solo genera texto en 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, incluido el uso de prompt para vocabulario.
Patrón 7: Diarización de Hablantes
Identifica quién habla en audio con varios interlocutores. Usa gpt-4o-transcribe-diarize con response_format: "diarized_json" y chunking_strategy: "auto" (obligatorio 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 URLs 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 (priorizando coste) -> 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 del hablante -> gpt-4o-transcribe-diarize
+-- Salida progresiva/en streaming -> gpt-4o-transcribe (stream: true)
Qué Formato de Respuesta Usar
¿Qué salida necesitas?
+-- Cadena de texto plano -> "text"
+-- JSON con campo text -> "json" (por defecto)
+-- Subtítulos para vídeo -> "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 > 30 segundos (la API devuelve un error) - Usar
stream: trueconwhisper-1(no es compatible)
Problemas de Prioridad Media:
- Usar
whisper-1cuandogpt-4o-transcribeproporcionaría una 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 con ruido) - Usar
audio.translations.create()cuando quieres transcripción en el mismo idioma (la traducción siempre genera texto en inglés) - Dividir el audio a mitad de una oración al fragmentar (se pierde el contexto en los límites)
Errores Comunes:
- Tratar el parámetro
promptcomo una instrucción ("transcribe con cuidado") cuando en realidad es contexto para el vocabulario y la coincidencia de estilo - Usar
gpt-4o-transcribecuando necesitas salida SRT/VTT; solowhisper-1admite esos formatos - Esperar que
gpt-4o-transcribe-diarizeadmita prompts o logprobs (no lo hace) - Usar el endpoint de traducción para audio en inglés (solo traduce audio que no está en 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 Situaciones Límite:
- 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 en silencio o casi silencio. Usano_speech_probdeverbose_jsonpara detectarlo.gpt-4o-transcribeygpt-4o-mini-transcribesolo admiten los formatos de respuestajsonytext, nosrt,vttniverbose_json.- El parámetro
languageusa códigos ISO 639-1 (por ejemplo,"en","fr","ja"). Establecerlo mejora la precisión para audio corto. - Formatos de archivo admitidos: 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 genera texto en 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]