Communitygithub.com

majiayu000/claude-skill-registry

Transcripción de voz a texto y traducción a través de la API de Audio de OpenAI: modelos, formatos de respuesta, marcas de tiempo, prompting, transmisión, fragmentación y diarización.

¿Qué es claude-skill-registry?

Este skill proporciona un conjunto completo de patrones para trabajar con la API de Audio de OpenAI, específicamente para tareas de transcripción de voz a texto (speech-to-text) y traducción de audio. Es ideal para desarrolladores y agentes de IA que necesitan procesar archivos de audio de manera programática, ofreciendo una guía clara sobre cómo seleccionar el modelo correcto (`whisper-1`, `gpt-4o-transcribe`, etc.) según la precisión, el costo, la necesidad de marcas de tiempo, subtítulos (SRT/VTT) o la identificación de hablantes (diarización). El skill cubre aspectos críticos como la fragmentación de archivos que superan los 25 MB, el uso del parámetro `prompt` para mejorar el vocabulario, la transcripción en streaming y la traducción a inglés de audio en otros idiomas. Además, detalla las limitaciones de cada modelo y formato de respuesta, y proporciona un marco de decisión para elegir la configuración óptima según el caso de uso, evitando errores comunes como usar `whisper-1` con `stream: true` o no usar el formato `verbose_json` para obtener marcas de tiempo.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry/tree/HEAD/skills/ai-llm/api-ai-openai-whisper

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Patrones de OpenAI Whisper

Guía rápida: Usa client.audio.transcriptions.create() para convertir voz a texto y client.audio.translations.create() para traducir audio que no esté en inglés a texto en inglés. Elige gpt-4o-transcribe para la máxima precisión, gpt-4o-mini-transcribe para eficiencia de costes, whisper-1 para marcas de tiempo/SRT/VTT, o gpt-4o-transcribe-diarize para identificar al hablante. Los archivos deben tener un tamaño inferior a 25 MB; fragmenta archivos más grandes. Usa prompt para guiar el vocabulario y el estilo. La transmisión en streaming está disponible mediante stream: true para obtener resultados progresivos con los modelos gpt-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 prompt para 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


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:

  1. La selección del modelo importa: gpt-4o-transcribe produce la mayor precisión con tasas de alucinación más bajas. whisper-1 es el único modelo que admite SRT/VTT/verbose_json con marcas de tiempo. gpt-4o-transcribe-diarize añade la identificación del hablante.
  2. 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.
  3. El uso de prompt mejora la precisión: el parámetro prompt guí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.
  4. El formato de respuesta determina las funciones disponibles: las marcas de tiempo requieren verbose_json en whisper-1. La diarización requiere diarized_json. SRT/VTT solo están disponibles en whisper-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ísticawhisper-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
Formatos de respuestajson, text, srt, vtt, verbose_jsonjson, textjson, textjson, text, diarized_json
Marcas de tiempopalabra + segmentoNoNoNo
StreamingNoSíSíNo
Soporte de promptSí (224 tokens)SíSíNo
LogprobsNoSíSíNo
Etiquetas de hablanteNoNoNoSí
Parámetro de idiomaSí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_granularities sin response_format: "verbose_json" en whisper-1 (se ignora silenciosamente)
  • Enviar archivos de más de 25 MB (la API devuelve un error)
  • Usar gpt-4o-transcribe-diarize sin chunking_strategy en audio > 30 segundos (la API devuelve un error)
  • Usar stream: true con whisper-1 (no es compatible)

Problemas de Prioridad Media:

  • Usar whisper-1 cuando gpt-4o-transcribe proporcionaría una mayor precisión (whisper-1 tiene tasas de alucinación más altas)
  • No pasar el parámetro language cuando 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 prompt como una instrucción ("transcribe con cuidado") cuando en realidad es contexto para el vocabulario y la coincidencia de estilo
  • Usar gpt-4o-transcribe cuando necesitas salida SRT/VTT; solo whisper-1 admite esos formatos
  • Esperar que gpt-4o-transcribe-diarize admita 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 prompt está limitado a aproximadamente 224 tokens en whisper-1. Los prompts más largos se truncan.
  • whisper-1 puede alucinar texto para segmentos de audio en silencio o casi silencio. Usa no_speech_prob de verbose_json para detectarlo.
  • gpt-4o-transcribe y gpt-4o-mini-transcribe solo admiten los formatos de respuesta json y text, no srt, vtt ni verbose_json.
  • El parámetro language usa 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-diarize etiqueta a los hablantes como "A", "B", "C" a menos que proporciones known_speaker_names y known_speaker_references con clips de audio cortos.
  • El endpoint de traducción solo admite whisper-1 y 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.delta con una propiedad de cadena delta, además de un evento final transcript.text.done.

</red_flags>


<critical_reminders>

RECORDATORIOS CRÍTICOS

**

...

[truncado para la traducción]

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

majiayu000/claude-skill-registry

Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry

Analyzes current state and user query to answer BMad questions or recommend the next workflow or agent. Use when user says what should I do next, what do I do now, or asks a question about BMad

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Build AI agents with Google ADK Python (Agent Development Kit). Use for multi-agent systems, workflow agents (sequential/parallel/loop), Vertex AI deployment, tool integration, human-in-the-loop.

majiayu000/claude-skill-registry

Portfolio allocation and rebalancing optimizer. Manages asset allocation across stocks/cash/bonds, performs periodic rebalancing, and ensures diversification according to market regime and risk tolerance.

majiayu000/claude-skill-registry

Create a hilarious and ultra-realistic video of an anthropomorphic animal acting like a human vlogger in a real-world setting.

majiayu000/claude-skill-registry

BlockRun works with Claude Code and Google Antigravity.

majiayu000/claude-skill-registry

This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.

majiayu000/claude-skill-registry

小省导购员数字人带货版即梦视频提示词生成系统,基于四大智能体协同(提示词生成师、质量管控师、知识库运维师、跨环节适配师),按照"主体+运动+场景+(镜头语言+光影+氛围)"公式输出中英文双版提示词,适配5s短视频。确保人物一致性、视觉连贯性、情绪连贯性,支持知识库智能复用和跨工具适配(Suno音乐、AI绘画),为数字人带货视频提供高质量提示词生成服务。

majiayu000/claude-skill-registry

Upload and manage files using Google Gemini File API via scripts/. Use for uploading images, audio, video, PDFs, and other files for use with Gemini models. Supports file upload, status checking, and file management. Triggers on "upload file", "file API", "upload image", "upload PDF", "upload video", "file management".

majiayu000/claude-skill-registry

CRITICAL: Use for MolyKit AI chat toolkit. Triggers on: BotClient, OpenAI, SSE streaming, AI chat, molykit, PlatformSend, spawn(), ThreadToken, cross-platform async, Chat widget, Messages, PromptInput, Avatar, LLM

majiayu000/claude-skill-registry

AI and machine learning workflow covering LLM application development, RAG implementation, agent architecture, ML pipelines, and AI-powered features.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Analyze images/audio/video with Gemini API (better vision than Claude). Generate images (Imagen 4), videos (Veo 3). Use for vision analysis, transcription, OCR, design extraction, multimodal AI.

majiayu000/claude-skill-registry

Conduct domain and industry research. Use when the user says "lets create a research report on [domain or industry]

majiayu000/claude-skill-registry

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Skills relacionados