Communitygithub.com

majiayu000/claude-skill-registry-data

Transcripción de voz a texto y traducción mediante la API de Audio de OpenAI: modelos, formatos de respuesta, marcas de tiempo, indicaciones, streaming, fragmentación y diarización.

¿Qué es claude-skill-registry-data?

Este skill proporciona patrones y buenas prácticas para utilizar la API de Audio de OpenAI en tareas de transcripción de voz a texto y traducción. Está diseñado para desarrolladores que trabajan con asistentes de IA como Claude Code, Cursor o Codex, y ofrece una guía detallada sobre la selección de modelos (como `gpt-4o-transcribe` para alta precisión, `whisper-1` para subtítulos SRT/VTT o marcas de tiempo, y `gpt-4o-transcribe-diarize` para identificación de hablantes), formatos de respuesta (JSON, texto, SRT, VTT, verbose_json y diarized_json), el uso de parámetros como `prompt` para mejorar la precisión del vocabulario, la fragmentación de archivos de audio mayores a 25 MB, la transmisión en streaming de resultados progresivos y la diarización de hablantes. Su utilidad radica en evitar errores comunes y optimizar el uso de la API, proporcionando ejemplos de código y un marco de decisión claro. Es especialmente valioso para proyectos que requieren transcripciones precisas de reuniones, entrevistas, podcasts o notas de voz, así como la generación de subtítulos y la traducción de audio no inglés a texto en inglés.

Compatible con✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/majiayu000/claude-skill-registry-data/tree/HEAD/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 voz a texto y client.audio.translations.create() para audio no inglés a texto en inglés. Elige gpt-4o-transcribe para máxima precisión, gpt-4o-mini-transcribe para eficiencia de costos, whisper-1 para marcas de tiempo/SRT/VTT, o gpt-4o-transcribe-diarize para identificación de hablantes. Los archivos deben tener menos de 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 salida progresiva en modelos gpt-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


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:

  1. La selección del modelo es importante -- 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 agrega identificación de hablantes.
  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. Las indicaciones mejoran la precisión -- El parámetro prompt guía el vocabulario, los acrónimos y el formato de estilo. No da instrucciones, sino que proporciona contexto con el que el modelo compara.
  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 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í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: 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_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 de más de 30 segundos (la API devuelve un error)
  • Usar stream: true con whisper-1 (no compatible)

Problemas de Prioridad Media:

  • Usar whisper-1 cuando gpt-4o-transcribe produciría 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 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 prompt como una instrucción ("transcribe cuidadosamente"): es contexto para la coincidencia de vocabulario y 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 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 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 silenciosos o casi silenciosos. Usa no_speech_prob de verbose_json para detectarlo.
  • gpt-4o-transcribe y gpt-4o-mini-transcribe solo admiten 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"). 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-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 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.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-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD agents while maintaining compliance

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

Edit existing BMAD modules while maintaining coherence

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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-data

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-data

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-data

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

majiayu000/claude-skill-registry-data

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

majiayu000/claude-skill-registry-data

Conduct market research on competition and customers. Use when the user says "create a market research report about [business idea]".

majiayu000/claude-skill-registry-data

Conduct technical research on technologies and architecture. Use when the user says "create a technical research report on [topic]".

majiayu000/claude-skill-registry-data

Understand an existing codebase through systematic exploration

majiayu000/claude-skill-registry-data

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".

Skills relacionados