Communitygithub.com

majiayu000/claude-skill-registry-data

Transcription et traduction de la parole en texte via l'API Audio OpenAI — modèles, formats de réponse, horodatages, instructions, streaming, découpage en segments et diarisation

Qu'est-ce que claude-skill-registry-data ?

Ce skill fournit un guide complet pour utiliser l'API Audio d'OpenAI afin de transcrire et traduire des fichiers audio. Il couvre la sélection du modèle (whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize), les formats de réponse (json, text, srt, vtt, verbose_json, diarized_json), les horodatages, la génération de sous-titres, les instructions pour le vocabulaire et le style, le découpage des fichiers volumineux (>25 Mo), le streaming, et l'identification des locuteurs. Il est essentiel pour les développeurs qui travaillent avec l'API Audio OpenAI dans des environnements comme Claude Code, Cursor ou Codex, et qui ont besoin de règles claires pour éviter les pièges courants (comme l'utilisation de formats de réponse incompatibles ou l'oubli de la limite de taille de fichier). Le skill détaille chaque cas d'usage avec des exemples de code TypeScript et un arbre de décision pour choisir le bon modèle et format.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Modèles OpenAI Whisper

Guide rapide : Utilisez client.audio.transcriptions.create() pour la transcription parole-texte et client.audio.translations.create() pour traduire un audio non-anglais en texte anglais. Choisissez gpt-4o-transcribe pour la meilleure précision, gpt-4o-mini-transcribe pour un bon rapport coût-efficacité, whisper-1 pour les horodatages/SRT/VTT, ou gpt-4o-transcribe-diarize pour l'identification des locuteurs. Les fichiers doivent faire moins de 25 Mo — découpez les fichiers plus gros. Utilisez prompt pour guider le vocabulaire et le style. Le streaming est disponible via stream: true pour une sortie progressive sur les modèles gpt-4o-transcribe.


<critical_requirements>

CRITIQUE : Avant d'utiliser ce skill

Tout le code doit suivre les conventions du projet dans CLAUDE.md (kebab-case, exports nommés, ordre des imports, import type, constantes nommées)

(Vous DEVEZ choisir le bon modèle pour le cas d'usage — gpt-4o-transcribe pour la précision, whisper-1 pour les horodatages/sorties SRT/VTT, gpt-4o-transcribe-diarize pour les étiquettes de locuteur)

(Vous DEVEZ découper les fichiers audio de plus de 25 Mo avant de les envoyer à l'API — l'API rejette les fichiers dépassant cette limite)

(Vous DEVEZ passer response_format: "verbose_json" lorsque vous utilisez timestamp_granularities — les horodatages ne fonctionnent qu'avec ce format sur whisper-1)

(Vous DEVEZ définir chunking_strategy: "auto" lorsque vous utilisez gpt-4o-transcribe-diarize avec un audio de plus de 30 secondes — l'API l'exige)

</critical_requirements>


Détection automatique : 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

Quand utiliser :

  • Transcrire des fichiers audio (réunions, entretiens, podcasts, notes vocales) en texte
  • Traduire un audio non-anglais en texte anglais
  • Générer des sous-titres au format SRT ou VTT à partir d'audio
  • Obtenir des horodatages au niveau du mot ou du segment pour le montage vidéo
  • Identifier les locuteurs dans un audio multipiste (diarisation)
  • Diffuser les résultats de transcription progressivement à mesure que le modèle traite l'audio

Principaux modèles couverts :

  • Sélection du modèle (whisper-1 vs gpt-4o-transcribe vs gpt-4o-mini-transcribe vs gpt-4o-transcribe-diarize)
  • Formats de réponse (json, text, srt, vtt, verbose_json, diarized_json)
  • Horodatages (niveau mot, niveau segment) et génération de sous-titres
  • Instructions pour le vocabulaire, les acronymes et le style
  • Découpage des fichiers volumineux (> 25 Mo) avec conservation du contexte
  • Streaming de transcription avec stream: true
  • Traduction vers l'anglais via audio.translations.create()
  • Diarisation des locuteurs avec références aux locuteurs

Quand NE PAS utiliser :

  • Synthèse vocale (TTS) — utilisez l'API TTS d'OpenAI (client.audio.speech.create())
  • Conversations vocales bidirectionnelles en temps réel — utilisez l'API Realtime d'OpenAI
  • Transcription avec des fournisseurs non OpenAI — utilisez un SDK vocal indépendant du fournisseur

Index des exemples


Philosophie

L'API Audio d'OpenAI fournit la transcription et la traduction de la parole en texte via plusieurs modèles optimisés pour différents besoins. L'API est simple — vous envoyez un fichier audio et récupérez du texte — mais choisir le bon modèle, le bon format de réponse et les bons paramètres est essentiel pour obtenir des résultats de qualité.

Principes fondamentaux :

  1. Le choix du modèle est crucial — gpt-4o-transcribe offre la meilleure précision avec des taux d'hallucination plus faibles. whisper-1 est le seul modèle prenant en charge SRT/VTT/verbose_json avec horodatages. gpt-4o-transcribe-diarize ajoute l'identification des locuteurs.
  2. La taille du fichier est la contrainte principale — la limite de 25 Mo vous oblige à découper les audios plus longs. Coupez aux limites des phrases pour préserver le contexte.
  3. Les instructions améliorent la précision — Le paramètre prompt guide le vocabulaire, les acronymes et le style de formatage. Il ne donne pas d'instructions — il fournit un contexte auquel le modèle se réfère.
  4. Le format de réponse détermine les fonctionnalités disponibles — Les horodatages nécessitent verbose_json sur whisper-1. La diarisation nécessite diarized_json. SRT/VTT sont uniquement disponibles sur whisper-1.

Quand utiliser l'API Audio :

  • Vous avez besoin d'une transcription précise de fichiers audio enregistrés
  • Vous avez besoin de sous-titres (SRT/VTT) à partir d'audio
  • Vous devez identifier qui parle dans une conversation
  • Vous devez traduire un discours non-anglais en texte anglais

Quand NE PAS utiliser :

  • Chat vocal en temps réel — utilisez plutôt l'API Realtime
  • Synthèse vocale — utilisez client.audio.speech.create()
  • Vous avez besoin d'une transcription dans une langue cible autre que l'anglais (la traduction ne produit que de l'anglais)

Modèles principaux

Modèle 1 : Transcription de base

Envoyez un fichier audio et recevez du texte. Le modèle détecte automatiquement la langue.

const transcription = await client.audio.transcriptions.create({
  model: "gpt-4o-transcribe",
  file: createReadStream(audioPath),
});

Utilisez gpt-4o-transcribe pour la meilleure précision. N'utilisez pas whisper-1 avec verbose_json lorsque vous avez uniquement besoin de texte brut — cela ajoute une surcharge et a des taux d'hallucination plus élevés. Voir core.md pour des exemples complets.


Modèle 2 : Sélection du modèle

Chaque modèle a des capacités et des compromis distincts.

De quoi avez-vous besoin ?
+-- Meilleure précision, texte brut -> gpt-4o-transcribe
+-- Rentable, texte brut -> gpt-4o-mini-transcribe
+-- Horodatages (mot/segment) -> whisper-1 (verbose_json)
+-- Sous-titres SRT ou VTT -> whisper-1 (format srt/vtt)
+-- Identification des locuteurs -> gpt-4o-transcribe-diarize
+-- Sortie en streaming -> gpt-4o-transcribe ou gpt-4o-mini-transcribe

Matrice des capacités des modèles

Fonctionnalitéwhisper-1gpt-4o-transcribegpt-4o-mini-transcribegpt-4o-transcribe-diarize
Formats de réponsejson, text, srt, vtt, verbose_jsonjson, textjson, textjson, text, diarized_json
Horodatagesmot + segmentNonNonNon
StreamingNonOuiOuiNon
Support des instructionsOui (224 tokens)OuiOuiNon
LogprobsNonOuiOuiNon
Étiquettes de locuteurNonNonNonOui
Paramètre langueOuiOuiOuiOui

Modèle 3 : Instructions pour le vocabulaire et le style

Le paramètre prompt fournit du contexte — pas des instructions. Il guide l'orthographe des noms, des acronymes et le style de formatage. Ne l'utilisez pas pour donner des instructions comme "veuillez transcrire attentivement" — il correspond au contexte de style et de vocabulaire.

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,
});

Cas d'usage : Acronymes/noms propres, conservation du contexte entre les morceaux (passer la fin de la transcription précédente), maintien des mots de remplissage, consignes de style d'écriture. Voir core.md pour des exemples détaillés de vocabulaire.


Modèle 4 : Découpage des fichiers volumineux

Les fichiers audio dépassant 25 Mo doivent être divisés avant la transcription. Coupez aux limites des phrases (par exemple via ffmpeg) pour préserver le contexte. Passez la fin de la transcription précédente comme prompt pour assurer la continuité entre les morceaux.

const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 Mo
// Diviser avec ffmpeg : ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Ensuite, transcrire séquentiellement en passant le contexte précédent via prompt

Voir core.md pour l'implémentation complète du découpage avec validation de taille et conservation du contexte.


Modèle 5 : Streaming de transcription

Diffusez les résultats partiels de transcription au fur et à mesure que le modèle traite l'audio. Seuls gpt-4o-transcribe et gpt-4o-mini-transcribe prennent en charge stream: true. Écoutez les événements transcript.text.delta pour la sortie progressive et transcript.text.done pour la fin. N'utilisez PAS stream: true avec whisper-1 — ce n'est pas pris en charge.

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);
}

Voir core.md pour des exemples complets de streaming et de logprobs.


Modèle 6 : Traduction vers l'anglais

Traduisez un audio non-anglais en texte anglais. Seul whisper-1 est pris en charge via audio.translations.create(). Pour une transcription dans la même langue, utilisez plutôt audio.transcriptions.create(). La traduction ne produit que de l'anglais — il n'est pas possible de traduire vers d'autres langues.

const translation = await client.audio.translations.create({
  model: "whisper-1",
  file: createReadStream(audioPath),
});

Voir core.md pour des exemples complets de traduction, y compris les instructions de vocabulaire.


Modèle 7 : Diarisation des locuteurs

Identifiez qui parle dans un audio multipiste. Utilisez gpt-4o-transcribe-diarize avec response_format: "diarized_json" et chunking_strategy: "auto" (requis pour un audio > 30s). La diarisation ne prend pas en charge 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",
});

Vous pouvez éventuellement fournir known_speaker_names et known_speaker_references (extraits audio de 2 à 10 secondes sous forme d'URL de données) pour mapper des segments à des locuteurs connus (jusqu'à 4). Voir core.md pour des exemples complets de diarisation.


<decision_framework>

Cadre de décision

Quel modèle choisir

De quoi avez-vous besoin pour la transcription ?
+-- Juste du texte (meilleure précision) -> gpt-4o-transcribe
+-- Juste du texte (sensible au coût) -> gpt-4o-mini-transcribe
+-- Horodatages mot/segment -> whisper-1 (verbose_json)
+-- Fichiers de sous-titres SRT ou VTT -> whisper-1 (srt ou vtt)
+-- Identification des locuteurs -> gpt-4o-transcribe-diarize
+-- Sortie progressive/streaming -> gpt-4o-transcribe (stream: true)

Quel format de réponse utiliser

De quelle sortie avez-vous besoin ?
+-- Chaîne de texte brut -> "text"
+-- JSON avec champ text -> "json" (par défaut)
+-- Sous-titres pour vidéo -> "srt" ou "vtt" (whisper-1 uniquement)
+-- Horodatages (mot/segment) -> "verbose_json" (whisper-1 uniquement)
+-- Segments avec étiquettes de locuteur -> "diarized_json" (gpt-4o-transcribe-diarize uniquement)

Transcription vs Traduction

L'audio est-il en anglais ?
+-- OUI -> Utilisez audio.transcriptions.create()
+-- NON -> Voulez-vous la sortie dans la langue d'origine ?
    +-- OUI -> Utilisez audio.transcriptions.create() (détection automatique de la langue)
    +-- NON (voulez l'anglais) -> Utilisez audio.translations.create() (whisper-1 uniquement)

</decision_framework>


<red_flags>

SIGNAL D'ALARME

Problèmes de haute priorité :

  • Utiliser timestamp_granularities sans response_format: "verbose_json" sur whisper-1 (ignoré silencieusement)
  • Envoyer des fichiers de plus de 25 Mo (l'API renvoie une erreur)
  • Utiliser gpt-4o-transcribe-diarize sans chunking_strategy sur un audio > 30 secondes (l'API renvoie une erreur)
  • Utiliser stream: true avec whisper-1 (non pris en charge)

Problèmes de priorité moyenne :

  • Utiliser whisper-1 alors que gpt-4o-transcribe offrirait une meilleure précision (whisper-1 a des taux d'hallucination plus élevés)
  • Ne pas passer le paramètre language lorsque vous connaissez la langue (la détection automatique peut être erronée pour un audio court ou bruyant)
  • Utiliser audio.translations.create() lorsque vous souhaitez une transcription dans la même langue (la traduction produit toujours de l'anglais)
  • Couper l'audio en milieu de phrase lors du découpage (perte de contexte aux limites)

Erreurs courantes :

  • Traiter le paramètre prompt comme une instruction ("veuillez transcrire attentivement") — c'est un contexte pour la correspondance de vocabulaire et de style
  • Utiliser gpt-4o-transcribe lorsque vous avez besoin d'une sortie SRT/VTT — seul whisper-1 prend en charge ces formats
  • S'attendre à ce que gpt-4o-transcribe-diarize prenne en charge les instructions ou les logprobs (ce n'est pas le cas)
  • Utiliser le point de terminaison de traduction pour un audio anglais (il ne traduit que du non-anglais vers l'anglais)
  • Ne pas fournir le contexte du morceau précédent lors de la transcription de fichiers divisés (réduit la précision aux limites)

Pièges et cas particuliers :

  • Le paramètre prompt est limité à environ 224 tokens sur whisper-1. Les instructions plus longues sont tronquées.
  • whisper-1 peut halluciner du texte pour les segments audio silencieux ou quasi-silencieux. Utilisez no_speech_prob de verbose_json pour le détecter.
  • gpt-4o-transcribe et gpt-4o-mini-transcribe prennent en charge uniquement les formats de réponse json et text — pas srt, vtt ou verbose_json.
  • Le paramètre language utilise les codes ISO 639-1 (par exemple "en", "fr", "ja"). Le définir améliore la précision pour les audios courts.
  • Formats de fichiers pris en charge : flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, webm. Les autres formats doivent d'abord être convertis.
  • gpt-4o-transcribe-diarize étiquette les locuteurs comme "A", "B", "C" à moins que vous ne fournissiez known_speaker_names et known_speaker_references avec de courts extraits audio.
  • Le point de terminaison de traduction ne prend en charge que whisper-1 et ne produit que de l'anglais — il n'est pas possible de traduire vers d'autres langues via cette API.
  • Le streaming de transcription émet des événements transcript.text.delta avec une propriété de chaîne delta, plus un événement final transcript.text.done.

</red_flags>


<critical_reminders>

RAPPELS CRITIQUES

**

…

[contenu tronqué pour la traduction]

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 associés