Modèles OpenAI Whisper
Guide rapide : Utilisez
client.audio.transcriptions.create()pour la transcription parole-texte etclient.audio.translations.create()pour l'audio non-anglais vers le texte anglais. Choisissezgpt-4o-transcribepour la plus haute 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 volumineux. Utilisezpromptpour orienter le vocabulaire et le style. Le streaming est disponible viastream: truepour une sortie progressive sur les modèlesgpt-4o-transcribe.
<exigences_critiques>
CRITIQUE : Avant d'utiliser cette compétence
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 modèle approprié pour le cas d'usage – gpt-4o-transcribe pour la précision, whisper-1 pour les horodatages/sortie SRT/VTT, gpt-4o-transcribe-diarize pour les étiquettes de locuteurs)
(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)
</exigences_critiques>
Détection automatique : Whisper, whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe, gpt-4o-transcribe-diarize, audio.transcriptions, audio.translations, transcription, parole-texte, diarisation, diarized_json, timestamp_granularities, verbose_json
Quand l'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'un audio
- Obtenir des horodatages au niveau du mot ou du segment pour le montage vidéo
- Identifier les locuteurs dans un audio multipiste (diarisation)
- Streamer les résultats de transcription progressivement au fur et à 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
- Requêtes pour le vocabulaire, les acronymes et le style
- Découpage des fichiers volumineux (> 25 Mo) avec conservation du contexte
- Streaming de la transcription avec
stream: true - Traduction vers l'anglais via
audio.translations.create() - Diarisation des locuteurs avec références aux locuteurs
Quand NE PAS l'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 autres qu'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 recevez 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 :
- La sélection du modèle est importante –
gpt-4o-transcribeproduit la plus haute 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 oblige à découper les audios plus longs. Coupez aux limites des phrases pour préserver le contexte.
- Les requêtes améliorent la précision – Le paramètre
promptoriente le vocabulaire, les acronymes et le formatage. Il ne donne pas d'instructions – il fournit un contexte que le modèle utilise pour correspondre. - 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'un audio
- Vous avez besoin d'identifier qui parle dans une conversation
- Vous avez besoin de traduire un discours non-anglais en texte anglais
Quand NE PAS l'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 en retour. 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 plus haute précision. N'utilisez pas whisper-1 avec verbose_json lorsque vous n'avez besoin que de texte brut – cela ajoute de la 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 ?
+-- Plus haute 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 du modèle
| 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 requêtes | Oui (224 jetons) | Oui | Oui | Non |
| Logprobs | Non | Oui | Oui | Non |
| Étiquettes de locuteurs | Non | Non | Non | Oui |
| Paramètre de langue | Oui | Oui | Oui | Oui |
Modèle 3 : Requêtes 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 du formatage. Ne l'utilisez pas pour donner des instructions comme "veuillez transcrire soigneusement" – il correspond au contexte du style et du 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 (passez la fin de la transcription précédente), maintien des mots de remplissage, guide 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 la continuité entre les morceaux.
const MAX_FILE_SIZE_BYTES = 25 * 1024 * 1024; // 25 Mo
// Découper avec ffmpeg : ffmpeg -i long.mp3 -f segment -segment_time 600 -c copy chunk_%03d.mp3
// Puis 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 la taille et conservation du contexte.
Modèle 5 : Transcription en streaming
Obtenez des résultats de transcription partiels 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 une 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'y a aucun moyen 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 requêtes 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" (obligatoire pour un audio > 30 s). 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 les segments à des locuteurs connus (jusqu'à 4). Voir core.md pour des exemples complets de diarisation.
<cadre_decisionnel>
Cadre décisionnel
Quel modèle choisir
De quoi avez-vous besoin pour la transcription ?
+-- Juste du texte (plus haute 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 texte -> "json" (par défaut)
+-- Sous-titres pour vidéo -> "srt" ou "vtt" (whisper-1 uniquement)
+-- Horodatages (mot/segment) -> "verbose_json" (whisper-1 uniquement)
+-- Segments étiquetés par 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)
</cadre_decisionnel>
<drapeaux_rouges>
DRAPEAUX ROUGES
Problèmes de priorité élevée :
- 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 de plus de 30 secondes (l'API renvoie une erreur) - Utiliser
stream: trueavecwhisper-1(non supporté)
Problèmes de priorité moyenne :
- Utiliser
whisper-1alors quegpt-4o-transcribeproduirait une précision plus élevée (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()alors que vous voulez une transcription dans la même langue (la traduction produit toujours de l'anglais) - Couper l'audio au milieu d'une phrase lors du découpage (perd le contexte aux limites)
Erreurs courantes :
- Traiter le paramètre
promptcomme une instruction ("veuillez transcrire soigneusement") – c'est du contexte pour la correspondance du vocabulaire et du 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 requêtes 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 jetons surwhisper-1. Les requêtes plus longues sont tronquées. whisper-1peut halluciner du texte pour des segments audio silencieux ou quasi silencieux. Utilisezno_speech_probdeverbose_jsonpour le détecter.gpt-4o-transcribeetgpt-4o-mini-transcribene prennent en charge que les formats de réponsejsonettext– passrt,vtt, ouverbose_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 fichier 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 par "A", "B", "C" sauf si vous fournissezknown_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'y a aucun moyen de traduire vers d'autres langues via cette API. - La transcription en streaming émet des événements
transcript.text.deltaavec une propriété de chaînedelta, plus un événement finaltranscript.text.done.
</drapeaux_rouges>
<rappels_critiques>
RAPPELS CRITIQUES
**
…
[tronqué pour la traduction]