L'appel de base de l'API Whisper n'est pas compliqué : une requête POST, un fichier audio et une clé suffisent pour obtenir un texte. Ce qui prend réellement du temps, ce sont les détails : fichier de plus de 25 Mo, format refusé, horodatage absent, décalage de la chronologie après découpage d'un audio long.

Cet article suit l'ordre d'intégration : endpoint et authentification, formats et limites de taille, différence entre transcription et traduction, paramètres d'horodatage, appels en curl et Python, découpage des audios longs, erreurs courantes, puis une liste de migration.

Remarque : OpenAI et Whisper sont des marques de leurs détenteurs respectifs ; cet article est une description technique et n'a aucun lien de rattachement avec OpenAI. Capacités, limites de fichiers et base de facturation peuvent évoluer ; faites foi sur la documentation de l'éditeur et la documentation du site, les prix étant ceux de la page Tarifs des modèles. La prise en charge complète de l'interface audio par la passerelle d'exemple dépend de la documentation du site.

1. Vérifier l'endpoint et l'authentification

L'interface audio n'est pas sur le même chemin que celle du chat. La transcription utilise /v1/audio/transcriptions, la traduction /v1/audio/translations ; les deux sont en POST, avec un corps multipart/form-data et non JSON. L'authentification reprend le jeton Bearer de style OpenAI.

Élément Description
Endpoint de transcription POST /v1/audio/transcriptions
Endpoint de traduction POST /v1/audio/translations
En-tête d'authentification Authorization: Bearer <API_KEY>
Type de requête multipart/form-data
Base URL de l'éditeur https://api.openai.com/v1
Base URL de la passerelle https://ai.zhongshangqihang.com/v1, selon la prise en charge documentée

La clé reste côté serveur. Une clé présente dans un navigateur, une application ou un dépôt public équivaut à livrer le compte. Les passerelles ne transmettent pas toutes l'interface audio de la même façon : avant l'intégration, vérifiez la disponibilité du modèle sur la page Tarifs des modèles ou dans la documentation du site.

2. Formats pris en charge et limite de 25 Mo

Les formats d'entrée listés par l'éditeur sont mp3, mp4, mpeg, mpga, m4a, wav et webm, avec une limite de 25 Mo par fichier. Ne présumez pas que flac ou ogg passent : convertissez avant l'envoi.

Les 25 Mo sont une limite de taille de fichier, pas de durée. Plus le débit est élevé, plus la durée tenable dans la même taille est courte : un mp3 mono à 16 kHz peut contenir longtemps, un wav stéréo à 48 kHz dépasse parfois la limite en une quinzaine de minutes. Convertir avant l'envoi en 16 kHz, mono, mp3 ou wav est le prétraitement le plus fiable.

3. Transcription et traduction ne sont pas la même chose

/audio/transcriptions transforme l'audio en texte dans la langue d'origine : un audio en chinois produit du chinois ; /audio/translations traduit l'audio en anglais, la documentation de l'éditeur précisant que seule la traduction vers l'anglais est prise en charge, avec whisper-1. Pour des sous-titres en français, utilisez la transcription, pas l'interface de traduction.

Le paramètre de langue utilise les codes ISO-639-1, par exemple fr, en ou ja. Sans paramètre, le modèle détecte automatiquement, mais un audio court, mixte ou fortement accentué est facilement mal identifié. Quand la langue métier est connue, la préciser explicitement est plus sûr.

4. Exemple minimal en curl

curl "https://ai.zhongshangqihang.com/v1/audio/transcriptions" \
  -H "Authorization: Bearer $WHISPER_API_KEY" \
  -F "file=@meeting.mp3" \
  -F "model=whisper-1" \
  -F "language=fr" \
  -F "response_format=verbose_json" \
  -F "timestamp_granularities[]=segment"

Trois points d'attention : le champ fichier utilise -F ; timestamp_granularities[] conserve les crochets ; seul verbose_json renvoie une structure par segments. Si la passerelle n'expose pas un paramètre, retirez-le d'abord et testez, puis isolez progressivement le problème.

5. Appel Python et horodatage

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["WHISPER_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

with open("meeting.mp3", "rb") as f:
    result = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        language="fr",
        response_format="verbose_json",
        timestamp_granularities=["segment"],
    )

for seg in result.segments:
    print(f"{seg.start:.1f}-{seg.end:.1f}  {seg.text}")

L'horodatage existe à deux niveaux : segment au niveau du segment de phrase, adapté aux sous-titres et comptes rendus de réunion ; word au niveau du mot, adapté à l'alignement mot à mot. La documentation de l'éditeur indique que timestamp_granularities[] ne s'applique actuellement qu'à whisper-1 et exige verbose_json. Les modèles de transcription plus récents peuvent être plus précis, mais la prise en charge des horodatages et des formats de sous-titres diffère : consultez la documentation avant de choisir.

Pour un domaine riche en noms propres, utilisez prompt pour fournir noms de personnes, de produits et termes techniques. La documentation indique une limite de 224 tokens pour le prompt de whisper-1, au-delà de laquelle il peut être tronqué : ne gardez que les termes essentiels.

Si seul le texte importe, utilisez json ou text pour response_format ; pour un fichier de sous-titres, demandez directement srt ou vtt. Plus le format est riche, plus la réponse est volumineuse : en traitement par lots, pesez la bande passante et le coût d'analyse.

6. Découper les audios longs avant transcription

Un audio de plus de 25 Mo doit être découpé. Procédure recommandée :

  1. Convertir avec ffmpeg en 16 kHz mono pour réduire le volume.
  2. Découper par détection de silence ou par tranches fixes de 10 minutes, en évitant de couper au milieu d'une phrase.
  3. Consigner l'offset de départ de chaque segment, par exemple part_000 à 0 seconde et part_001 à 600 secondes.
  4. Appeler la transcription segment par segment et conserver la réponse brute.
  5. À la fusion, rajouter l'offset aux horodatages de chaque segment.
  6. Vérifier par échantillonnage autour des points de coupe, pour traiter les mots répétés et les pertes.

Un chevauchement de 0,5 à 1 seconde entre segments réduit les pertes aux frontières, mais la partie recouverte est transcrite deux fois : la fusion doit dédupliquer. Le script de découpage doit enregistrer la liste des offsets en même temps que les fichiers ; ne devinez pas le temps à partir du nom de fichier. Une incohérence entre noms, ordre et offsets est l'incident le plus fréquent à la fusion. La concurrence raccourcit la durée totale, mais ne dépassez pas la limite de débit du compte : les reprises sur 429 ralentiraient l'ensemble.

7. Diagnostic des erreurs courantes

  • 401 : clé erronée, expirée, ou Bearer absent.
  • 404 : Base URL ou chemin incorrect ; vérifiez /v1/audio/transcriptions.
  • 400 : format non pris en charge, paramètre mal orthographié, ou modèle ne prenant pas en charge ce paramètre.
  • 413 : fichier au-delà de la limite de taille ; compressez ou découpez.
  • 429 : concurrence ou quota dépassé ; réduisez la concurrence et appliquez un backoff exponentiel.
  • 5xx ou délai dépassé : problème serveur ou réseau ; limitez les reprises pour éviter la double facturation.
  • Texte vide : audio silencieux, volume trop faible ou langue mal détectée ; vérifiez l'audio et précisez language.
  • Horodatage absent : response_format n'est pas verbose_json, ou le modèle n'est pas whisper-1.

8. Liste de migration de l'éditeur vers une passerelle

  1. Confirmer le Base URL de la passerelle cible et le chemin de l'interface audio.
  2. Vérifier que le modèle voulu est disponible sur le site, avec le même nom que chez l'éditeur.
  3. Remplacer le corps JSON par multipart/form-data.
  4. Aligner response_format et vérifier si le code dépend du champ segments.
  5. Valider la prise en charge des paramètres d'horodatage ; sinon, revenir au niveau segment ou à un alignement local.
  6. Définir des délais et un nombre maximal de tentatives raisonnables.
  7. Ne pas journaliser l'adresse audio complète ni la clé ; traiter le texte produit comme une donnée sensible.
  8. Exécuter une régression sur un jeu d'audios métier réels, en comparant taux d'erreur de caractères et chronologie.
  9. Prévoir une voie de repli : autre modèle, autre région, ou retour à l'interface de l'éditeur.

Questions fréquentes

Quelle différence entre l'API Whisper et le modèle Whisper open source ?

Le modèle open source peut être déployé soi-même, avec les données conservées localement, mais il faut assumer GPU, exploitation et optimisation. L'API hébergée évite le déploiement, facture à l'usage et convient à une mise en ligne rapide avec un trafic variable.

Les 25 Mo sont-ils une limite de durée audio ?

Non, une limite de taille de fichier. Réduire le débit et passer en mono allonge sensiblement la durée possible ; au-delà de la limite, découpez.

Pourquoi ne pas obtenir d'horodatage au niveau du mot ?

L'horodatage au niveau du mot exige simultanément whisper-1, verbose_json et timestamp_granularities=["word"]. Un changement de modèle ou de format peut faire disparaître le champ.

L'interface de traduction peut-elle traduire de l'anglais vers le français ?

Non. L'interface de traduction de l'éditeur ne produit que de l'anglais. Pour un contenu en français, utilisez la transcription, puis un modèle texte pour la traduction.

Une passerelle peut-elle remplacer directement le Base URL de l'éditeur ?

Pour les interfaces texte, généralement oui ; pour l'audio, cela dépend de la transmission du chemin et des paramètres par la passerelle. Validez avec un court audio avant l'intégration, sans présumer de la compatibilité.

Pour aller plus loin

Créez un compte ZSQH AI Gateway, créez une clé de test, validez une transcription avec un audio d'une minute, puis vérifiez l'horodatage et le découpage des audios longs. Les modèles et prix sont sur la page Tarifs des modèles.

Pour aller plus loin :