API Whisper-1 : votre première transcription audio

Une première requête à l’API Whisper-1 nécessite un fichier audio, un ID de modèle explicite et un format de sortie. Sur SeedRouter, vous envoyez l’enregistrement, conservez l’ID de tâche renvoyé, puis téléchargez la transcription lorsque cette tâche se termine. Commencez par un court enregistrement dont vous connaissez déjà les mots : vous repérerez plus facilement les omissions et les orthographes inhabituelles.

Ce guide suit le contrat asynchrone de SeedRouter. Ce n’est pas un exemple synchrone du SDK OpenAI utilisable tel quel. La page du modèle Whisper-1 propose le Playground et le tarif en vigueur ; la référence API répertorie chaque champ et les vérifications de compatibilité restantes. ^[1]

Préparer un enregistrement

Utilisez de la parole que vous avez l’autorisation de traiter. Un court WAV ou MP3 est un bon point de départ. La limite d’envoi actuelle est de 26 214 400 octets ; le fichier doit contenir un audio lisible d’une durée mesurable. Une extension .mp3 ne transforme pas un fichier texte renommé en audio valide. La référence distingue les neuf formats d’entrée documentés de ceux qui ont passé des vérifications réelles. ^[1]

L’enregistrement ci-dessous est une création originale de parole synthétique anglaise, réalisée pour ce tutoriel. Sa forme d’onde apparaît sur la couverture. La phrase citée sur la couverture provient du script de l’enregistrement et ne constitue pas une affirmation de précision.

Télécharger l’extrait de 10,31 secondes. Le script dit : “This is a sample recording for an audio transcription tutorial. Our meeting starts at nine thirty on Monday. Please bring the project notes and review the final checklist before we begin.”

Conservez une clé API dans une variable d’environnement côté serveur. Ne la placez pas dans une page web publique, un paquet d’application mobile ou une capture d’écran partagée. L’exemple Python ci-dessous utilise requests et lit SEEDROUTER_API_KEY dans l’environnement.

Envoyer la requête API Whisper-1 une seule fois

Choisissez json pour une première requête. Vous pourrez ensuite lire le champ text du résultat téléchargé sans gérer les codes temporels des sous-titres. La partie multipart file doit contenir de vrais octets ; fournir une URL comme valeur n’équivaut pas à envoyer le fichier. Laissez le client définir le type de contenu multipart et sa délimitation. ^[1]

Enregistrez ceci dans transcribe.py. Le script écrit un marqueur d’envoi avant le POST et sauvegarde l’ID de tâche accepté ensuite. Lors d’une nouvelle exécution, il lit cette tâche existante. Si l’issue du POST est incertaine, le marqueur empêche le script de créer un doublon accidentel.

import json
import os
from pathlib import Path

import requests

base = "https://api.seedrouter.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"}
state = Path("whisper-task.json")
audio = Path("recording.wav")

if not state.exists():
    if not 0 < audio.stat().st_size <= 26_214_400:
        raise ValueError("Choose a nonempty recording within the upload limit")
    with state.open("x") as marker:
        json.dump({"status": "submission_unconfirmed"}, marker)
    with audio.open("rb") as recording:
        response = requests.post(
            f"{base}/audio/transcriptions",
            headers=headers,
            files={"file": (audio.name, recording, "audio/wav")},
            data={"model": "whisper-1", "response_format": "json"},
            timeout=180,
            allow_redirects=False,
        )
    response.raise_for_status()
    accepted = response.json()
    task_id = accepted.get("id")
    if not isinstance(task_id, str) or not task_id.startswith("task_"):
        raise RuntimeError("Submission could not be confirmed; check task history")
    state.write_text(json.dumps({"id": task_id}), encoding="utf-8")

saved = json.loads(state.read_text(encoding="utf-8"))
if "id" not in saved:
    raise RuntimeError("Check task history before submitting another recording")

response = requests.get(
    f"{base}/tasks/{saved['id']}", headers=headers, timeout=30,
    allow_redirects=False,
)
response.raise_for_status()
task = response.json()
print(task["status"])
if task["status"] == "completed":
    result = requests.get(task["output"]["url"], timeout=60)
    result.raise_for_status()
    print(result.json()["text"])
elif task["status"] == "failed":
    print(task["error"])

Exécutez python transcribe.py. Si le script affiche processing, attendez quelques secondes puis relancez la même commande. Il lira l’ID enregistré au lieu d’envoyer à nouveau le fichier. Utilisez un fichier d’état distinct pour chaque nouvel enregistrement volontaire. Un délai client dépassé ne suffit pas à établir l’échec d’une tâche.

Lire la transcription terminée

La réponse d’acceptation contient id, model, status et created_at. À la fin, output.url et output.format sont ajoutés. Cette URL pointe vers le fichier résultat ; ce n’est pas une tâche de génération de média qui exige une autre requête payante. Une requête GET télécharge le résultat. ^[1]

Lisez les mots en écoutant l’enregistrement. Vérifiez les noms, les nombres et les limites de phrases avant d’utiliser le texte comme sous-titres ou citation exacte. Une transcription est une ébauche de ce qui a été dit, et l’horodatage ne dispense pas de la relire.

Les vérifications locales de bout en bout du 19 octobre 2026 ont terminé les cinq formats de transcription et une traduction à partir d’une entrée anglaise. Elles établissent le comportement de livraison et de facturation pour les enregistrements testés. Elles n’établissent ni pourcentage de précision ni qualité de traduction entre langues.

Choisir le texte, l’horodatage ou les sous-titres

Pour l’horodatage des mots, envoyez response_format=verbose_json et un champ multipart répété nommé timestamp_granularities[] avec la valeur word. Ajoutez une autre partie avec la valeur segment si vous voulez les deux. Dans Python requests, utilisez une liste de paires (name, value) pour les champs répétés. Chaque horodatage est en secondes. ^[2]

L’horodatage des mots et l’identification des locuteurs sont des sorties différentes. Whisper-1 ne transforme pas une réunion en transcription identifiant les locuteurs simplement parce que vous demandez des segments. Il ne diffuse pas non plus de texte partiel : stream est ignoré pour ce modèle. Omettez chunking_strategy pour le parcours vérifié ; la sélection explicite d’auto n’a pas passé la vérification réelle de compatibilité. ^[1]

Ajouter la langue et le contexte orthographique si nécessaire

Un paramètre facultatif language=en indique à la requête de transcription que l’entrée est en anglais. Omettez-le pour la détection. Si un nom de produit risque d’être mal compris, placez son orthographe correcte dans prompt, dans la même langue que l’audio. Les prompts Whisper fournissent du contexte ; ils ne se comportent pas comme une instruction de conversation permettant d’imposer de façon fiable une mise en page. ^[3]

Gardez un contexte pertinent pour l’extrait. Whisper ne prend en compte que les 224 derniers tokens de son propre tokenizer. Envoyer un long document ne fournit pas un glossaire illimité à l’enregistrement, et compter les caractères ne remplace pas cette règle de tokens de manière fiable.

Pour traduire vers l’anglais, remplacez l’endpoint par /audio/translations. Ses cinq champs de requête sont file, model, prompt, response_format et temperature. La traduction produit de l’anglais ; elle n’a pas de sélecteur de langue cible. Utilisez un prompt anglais si vous en fournissez un. ^[4]

Vérifier le coût avant d’étendre le traitement

Le tableau de tarifs actualisés ci-dessous utilise la durée audio mesurée. Une transcription plus longue n’augmente pas la facturation à la durée pour le même enregistrement. La durée de chaque fichier est arrondie à la seconde supérieure, puis convertie en unités de mesure audio. La référence API fournit le calcul exact et le Playground affiche une estimation dès qu’il peut lire la durée de l’enregistrement. Les requêtes échouées ne sont pas facturées.

Avant de traiter de nombreux fichiers, validez un enregistrement représentatif et examinez le résultat. Conservez son ID de tâche pour chaque enregistrement afin de reprendre après une interruption de connexion en consultant l’état existant. Consultez la référence complète des paramètres avant d’ajouter des sous-titres ou des combinaisons de formats moins testées.

Questions pour une première intégration

Puis-je utiliser l’exemple du SDK Python OpenAI sans le modifier ?

Non. Les champs d’entrée multipart sont familiers, mais SeedRouter renvoie un ID de tâche asynchrone. Un client synchrone qui attend text dans la réponse POST doit être adapté. Cet exemple rend explicites l’envoi et la lecture du résultat.

Pourquoi mon résultat JSON ne contient-il pas l’horodatage des mots ?

Le format par défaut json est une réponse orientée texte. Demandez ensemble verbose_json et la granularité d’horodatage word. Le minutage par segments seul ne crée pas une entrée par mot.

Dois-je envoyer un autre POST après un délai dépassé ?

Consultez d’abord l’ID de tâche sauvegardé ou l’historique des tâches. La réponse peut avoir été perdue après acceptation. Lire une tâche existante évite de créer une autre requête pour le même enregistrement.

Whisper-1 va-t-il être retiré ?

OpenAI a annoncé l’arrêt de Whisper dans sa propre API pour le 26 février 2027. Cet avis ne fixe pas de date d’arrêt pour ce service. Ajoutez les avis de cycle de vie à votre liste de maintenance lors de la création d’une intégration. ^[5]

Sources

[1] Référence API Whisper-1 de SeedRouter et état de vérification, vérifiés le 19 octobre 2026.

[2] Référence de transcription OpenAI.

[3] Guide OpenAI des prompts Whisper.

[4] Référence de traduction OpenAI.

[5] Avis OpenAI de dépréciation des modèles de transcription.