Modèles OpenAI Whisper
Guide rapide : Utilisez
client.audio.transcriptions.create()pour la transcription parole-texte etclient.audio.translations.create()pour traduire un audio non-anglais en texte anglais. Choisissezgpt-4o-transcribepour la meilleure précision,gpt-4o-mini-transcribepour un bon rapport coût-efficacité,whisper-1pour les horodatages/SRT/VTT, ougpt-4o-transcribe-diarizepour l'identification des locuteurs. Les fichiers doivent faire moins de 25 Mo — découpez les fichiers plus gros. Utilisezpromptpour guider le vocabulaire et le style. Le streaming est disponible viastream: truepour une sortie progressive sur les modèlesgpt-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
- Principal : Transcription, Traduction, Horodatages, Découpage, Streaming, Diarisation — Tous les modèles de l'API Audio
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 :
- Le choix du modèle est crucial —
gpt-4o-transcribeoffre la meilleure précision avec des taux d'hallucination plus faibles.whisper-1est le seul modèle prenant en charge SRT/VTT/verbose_json avec horodatages.gpt-4o-transcribe-diarizeajoute l'identification des locuteurs. - 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.
- Les instructions améliorent la précision — Le paramètre
promptguide 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. - Le format de réponse détermine les fonctionnalités disponibles — Les horodatages nécessitent
verbose_jsonsurwhisper-1. La diarisation nécessitediarized_json. SRT/VTT sont uniquement disponibles surwhisper-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-1 | gpt-4o-transcribe | gpt-4o-mini-transcribe | gpt-4o-transcribe-diarize |
|---|---|---|---|---|
| Formats de réponse | json, text, srt, vtt, verbose_json | json, text | json, text | json, text, diarized_json |
| Horodatages | mot + segment | Non | Non | Non |
| Streaming | Non | Oui | Oui | Non |
| Support des instructions | Oui (224 tokens) | Oui | Oui | Non |
| Logprobs | Non | Oui | Oui | Non |
| Étiquettes de locuteur | Non | Non | Non | Oui |
| Paramètre langue | Oui | Oui | Oui | Oui |
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_granularitiessansresponse_format: "verbose_json"surwhisper-1(ignoré silencieusement) - Envoyer des fichiers de plus de 25 Mo (l'API renvoie une erreur)
- Utiliser
gpt-4o-transcribe-diarizesanschunking_strategysur un audio > 30 secondes (l'API renvoie une erreur) - Utiliser
stream: trueavecwhisper-1(non pris en charge)
Problèmes de priorité moyenne :
- Utiliser
whisper-1alors quegpt-4o-transcribeoffrirait une meilleure précision (whisper-1 a des taux d'hallucination plus élevés) - Ne pas passer le paramètre
languagelorsque 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
promptcomme une instruction ("veuillez transcrire attentivement") — c'est un contexte pour la correspondance de vocabulaire et de style - Utiliser
gpt-4o-transcribelorsque vous avez besoin d'une sortie SRT/VTT — seulwhisper-1prend en charge ces formats - S'attendre à ce que
gpt-4o-transcribe-diarizeprenne 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
promptest limité à environ 224 tokens surwhisper-1. Les instructions plus longues sont tronquées. whisper-1peut halluciner du texte pour les segments audio silencieux ou quasi-silencieux. Utilisezno_speech_probdeverbose_jsonpour le détecter.gpt-4o-transcribeetgpt-4o-mini-transcribeprennent en charge uniquement les formats de réponsejsonettext— passrt,vttouverbose_json.- Le paramètre
languageutilise 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 fournissiezknown_speaker_namesetknown_speaker_referencesavec de courts extraits audio.- Le point de terminaison de traduction ne prend en charge que
whisper-1et 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.deltaavec une propriété de chaînedelta, plus un événement finaltranscript.text.done.
</red_flags>
<critical_reminders>
RAPPELS CRITIQUES
**
…
[contenu tronqué pour la traduction]