Documentation API

Utilisez https://api.transcript1.com/v1 comme URL de base pour vos appels API.

• Les appels et les réponses utilisent un corps JSON, avec des champs en snake_case.
• Les dates suivent ISO 8601 en UTC : 2026-10-13T09:30:00.000Z, par exemple.
• Les durées et les repères temporels des transcriptions sont en secondes.
• Le format des erreurs ne change pas d'un endpoint à l'autre. Consultez Erreurs pour sa structure.
• Après un appel authentifié, les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining indiquent votre limite et les requêtes encore disponibles. La page Facturation et limites donne les plafonds par offre.
• Avec source=auto, nous cherchons d'abord des sous-titres exploitables dans la langue d'origine sur YouTube, X, TikTok, Bluesky, Dailymotion et LinkedIn. S'il n'y en a pas, nous transcrivons l'audio. Le mode source=captions (sous-titres uniquement) ne télécharge pas l'audio et ne lance jamais le STT : sans piste exploitable, il renvoie no_captions. Pour passer directement à l'audio, choisissez source=stt ou demandez l'identification des locuteurs. Consultez les possibilités de chaque source pour les restrictions d'accès et la disponibilité des temps par segment ou par mot.

Pour vos outils, récupérez la spécification OpenAPI dans le format de votre choix :

• JSON
• YAML

Ajoutez votre clé API ou votre token OAuth à chaque appel avec l'en-tête Authorization: Bearer <token>.

• Clé API. Son préfixe est t1_. Créez votre clé dans « API keys » pour accéder à tous les endpoints.
• Token d'accès OAuth. Son préfixe est t1o_. Claude, ChatGPT et les autres clients MCP en reçoivent un lors de la connexion. Il porte les scopes transcriptions:read et transcriptions:write.

Scope	Appels autorisés
transcriptions:read	GET /v1/transcriptions, GET /v1/transcriptions/:id, GET /v1/transcriptions/:id/upload et GET /v1/account
transcriptions:write	POST /v1/transcriptions, DELETE /v1/transcriptions/:id et POST /v1/transcriptions/:id/upload/complete

• Si le token n'a pas le scope nécessaire, l'API répond 403 insufficient_scope.
• Sans clé ou token valide, elle répond 401 unauthorized.

Pour envoyer les blocs d'un fichier, utilisez plutôt X-Upload-Token sur PUT /v1/transcriptions/:id/upload/chunks/:index. Vous recevez ce token à la création de l'upload. La page Importer des fichiers décrit les étapes.

Ajoutez Idempotency-Key à vos appels POST /v1/transcriptions pour pouvoir les renvoyer sans créer de doublon.

Choisissez une clé de 1 à 255 caractères et placez-la dans cet en-tête HTTP, jamais dans les paramètres de l'URL.

• Si vous renvoyez la même clé avec les mêmes paramètres, vous retrouvez la transcription d'origine sans consommer de nouvelles minutes.
• Si vous gardez la clé mais changez les paramètres, l'API répond 409 idempotency_conflict.
• Pour un upload en blocs, renvoyer l'appel de création avec cette même clé génère un nouveau token d'upload.

• Si l'API refuse votre appel, vous recevez une erreur de requête.
• Si elle accepte la transcription mais que le traitement échoue ensuite, la transcription passe au status failed.

Lire une réponse d'erreur

Quand l'API refuse un appel /v1, la réponse contient un objet error. Vous y trouverez code, message et retryable.

• Dans votre code, choisissez l'action à effectuer à partir de code.
• Pour expliquer le problème à l'utilisateur, affichez message. Ne vous basez pas sur son texte pour votre logique : la formulation peut évoluer.
• Si retryable vaut true, vous pouvez retenter le même appel plus tard.

Selon l'erreur, d'autres champs complètent cet objet au même niveau que retryable :

Champ	Code concerné	Informations fournies
action_url	insufficient_minutes	Lien pour souscrire une offre ou acheter une recharge.
minutes_needed, minutes_remaining	insufficient_minutes	Minutes nécessaires pour cet appel (null si ce nombre n'est pas encore connu) et solde disponible.
supported_platforms	unsupported_platform	Liste des plateformes acceptées : ["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"].
missing_chunks	upload_incomplete	Index des blocs à envoyer de nouveau.
max_bytes	media_too_large	Taille maximale des fichiers pour votre compte, en octets.
params	invalid_request	Pour les erreurs de validation du corps ou des paramètres d'URL, détail du problème pour chaque champ concerné.

Quand l'API refuse un appel

Statut HTTP	code	Peut réussir sans correction ?	Cause et action à effectuer
400, 422	invalid_request	Non	Il manque un paramètre ou un champ, ou sa valeur n'est pas valide. Vérifiez notamment les combinaisons interdites : diarize avec source: "captions", ou reuse_recent avec webhook_url. Ce code signale aussi un corps JSON invalide.
422	invalid_url	Non	Le lien doit venir de YouTube, X, TikTok, Instagram, Facebook, Bluesky ou d'une autre plateforme de la liste Sources et options. Si vous indiquez platform, sa valeur doit correspondre au lien.
422	unsupported_platform	Non	La valeur de platform ne correspond à aucune plateforme acceptée.
422	unsupported_media	Non	L'extension du fichier importé n'est pas acceptée.
401	unauthorized	Non	La clé ou le token manque, n'est pas valide, a expiré ou a été révoqué. Pour un token d'upload, il est invalide ou expiré.
403	insufficient_scope	Non	Le token OAuth n'a pas le scope transcriptions:read ou transcriptions:write nécessaire à cet appel.
403	email_not_verified	Non	Confirmez votre adresse e-mail pour pouvoir lancer une transcription.
402	insufficient_minutes	Non	Votre solde utilisable est à 0 ou ne couvre pas la durée de la transcription.
402	no_active_plan	Non	Vous essayez d'acheter une recharge sans offre payante active. Ce code vient de l'endpoint de facturation du tableau de bord, jamais des endpoints de transcription.
404	not_found	Non	Aucune transcription ne correspond, ou elle appartient à une autre équipe.
409	upload_incomplete	Non	Certains blocs ne sont pas arrivés. Envoyez les blocs manquants, puis relancez la finalisation de l'upload.
409	invalid_state	Non	Le statut de la transcription n'autorise pas l'upload. Vous ne pouvez donc ni envoyer de blocs ni finaliser l'upload.
409	idempotency_conflict	Non	Vous avez déjà utilisé cette Idempotency-Key avec d'autres paramètres.
413	media_too_large	Non	Le fichier dépasse la taille autorisée. Consultez Importer des fichiers.
413	invalid_request	Non	Le corps JSON dépasse 1 Mo. Pour un fichier trop volumineux, le code est media_too_large.
429	rate_limited	Oui	Vous avez dépassé le nombre d'appels par minute. Attendez le délai en secondes donné par Retry-After.
429	too_many_active_jobs	Oui	Trop de transcriptions tournent en parallèle ou trop d'uploads restent ouverts. Attendez le délai en secondes donné par Retry-After.
500	internal_error	Oui	Notre serveur a rencontré une erreur. Réessayez dans un instant.
503	service_unavailable	Oui	transcript1 est temporairement indisponible. Réessayez dans un instant.

Pour les appels du navigateur authentifiés par un cookie de connexion, nous vérifions aussi l'origine. Si l'appel vient d'un autre site, vous recevez 403 forbidden_origin.

Ce contrôle ne concerne pas les appels qui utilisent un en-tête Authorization.

Toutes les réponses 429 incluent Retry-After, en secondes. Les plafonds de chaque offre figurent dans Facturation et limites.

Gérer les nouvelles tentatives

• Relancez automatiquement un appel seulement si retryable vaut true. C'est le cas pour rate_limited, too_many_active_jobs, internal_error et service_unavailable.
• Si la réponse fournit Retry-After, respectez ce délai. Sinon, augmentez progressivement l'attente entre les appels.
• Gardez la même valeur d'Idempotency-Key quand vous renvoyez POST /v1/transcriptions. Vous évitez ainsi de payer deux fois si le premier appel a abouti.
• Avec les autres codes, corrigez d'abord la cause de l'erreur.

Quand le traitement échoue après acceptation

Si la transcription passe au statut failed, consultez son objet error : il contient code et message.

L'appel de création peut avoir réussi avant que le traitement échoue. Vérifiez donc error lors de vos appels de suivi ou à la réception du webhook transcription.failed.

error.code	Cause	Que faire ?
media_unavailable	La vidéo est introuvable ou n'est plus accessible.	Ne relancez pas le même lien sans vérifier l'URL.
media_private	L'accès à la vidéo est privé.	Utilisez un post public, ou une vidéo YouTube publique ou non répertoriée. Relancer le même lien ne changera rien.
login_required	Il faut se connecter à la plateforme pour accéder à la vidéo.	Ne réessayez pas : cet échec est définitif et ne déclenche aucune nouvelle tentative.
no_audio	Aucune piste audio n'est présente dans la vidéo.	Ne réessayez pas : cet échec est définitif et ne déclenche aucune nouvelle tentative.
age_restricted	La plateforme limite la vidéo selon l'âge.	Ne relancez pas le lien ; importez plutôt le fichier.
live_stream	Le direct est encore en cours ou n'a pas commencé.	Attendez la fin du direct avant de réessayer.
no_captions	Vous avez choisi source avec la valeur captions, mais aucune piste de sous-titres n'est exploitable.	Choisissez source: "auto" ou "stt".
media_too_long	L'enregistrement dépasse les 5 heures acceptées pour le speech-to-text.	Découpez-le avant de l'envoyer de nouveau.
unsupported_media	Le fichier est illisible ou ne contient pas de piste audio.	Envoyez un fichier dans un format accepté plutôt que de relancer le même.
no_speech	Aucune parole détectée.	Inutile de relancer ce traitement.
unsupported_language	Nous ne prenons pas en charge la langue de l'enregistrement.	Corrigez language avec un code accepté ou "auto" avant de réessayer.
insufficient_minutes	Le solde ne suffisait plus au moment de facturer la transcription.	Achetez une recharge, puis réessayez.
fetch_failed	Le téléchargement a échoué malgré plusieurs tentatives.	Réessayez plus tard.
transcription_failed	Le speech-to-text a échoué malgré plusieurs tentatives.	Réessayez plus tard.

Si le traitement échoue ou si vous l'annulez, vous ne payez rien. Nous recréditons les minutes déjà prélevées.

Pour recevoir une notification en fin de traitement, fournissez webhook_url à la création de la transcription. Nous envoyons un POST signé à cette adresse si le traitement aboutit ou échoue.

Cette option est réservée à l'API REST : le serveur MCP ne propose pas de paramètre webhook.

Choisir l'adresse de réception

Sur POST /v1/transcriptions, placez webhook_url à l'endroit adapté à votre source :

• Dans le corps JSON pour un lien vidéo compatible ou pour réserver un upload en blocs.
• Dans un champ de formulaire pour un fichier envoyé en une seule requête.

Votre URL doit respecter ces conditions :

• utiliser HTTPS ;
• ne contenir ni nom d'utilisateur ni mot de passe ;
• se résoudre vers une adresse IP publique.

Une adresse privée, loopback, link-local ou toute autre adresse non publique provoque 422 invalid_request. Nous contrôlons l'adresse à la création de la transcription, puis avant chaque envoi.

N'utilisez pas webhook_url avec reuse_recent=true : ces options sont incompatibles.

Événements

type	Déclenchement
transcription.completed	Le statut passe à completed.
transcription.failed	Le statut passe à failed. Lisez le code et le message dans data.error.

Si vous annulez la transcription, nous n'envoyons pas de webhook.

Lire la notification

Vous recevez un corps JSON :

• created_at indique quand nous avons créé l'événement.
• data contient l'objet de transcription, sans le champ transcript.

Le texte se récupère séparément : prenez l'id dans data, puis appelez GET /v1/transcriptions/:id.

L'appel comporte aussi les en-têtes suivants :

• Content-Type: application/json
• User-Agent: transcript1-webhooks/1.0
• X-Transcript1-Signature, à vérifier comme indiqué ci-dessous.

Vérifier la signature

Pour chaque envoi, vous recevez X-Transcript1-Signature sous la forme t=<unix seconds>,v1=<hex digest>.

• t donne le timestamp Unix de la signature, en secondes.
• Pour calculer v1, appliquez HMAC-SHA256 à "<t>.<raw body>", puis encodez le condensat en hexadécimal. Assemblez la valeur de t, un point et le corps reçu sans aucune modification. La clé HMAC est votre secret de signature complet, y compris son préfixe whsec_.

Vérifiez la signature sur les octets du corps brut, avant de parser le JSON. Parser puis sérialiser de nouveau peut changer les espaces ou l'ordre des clés : la signature ne correspondrait plus.

• Utilisez une comparaison en temps constant pour les signatures.
• Refusez l'appel si t est trop éloigné de l'heure actuelle. Nos exemples acceptent un écart de 5 minutes.
• Avec Express, récupérez le corps en texte brut avant tout parsing.
• Avec Flask, fournissez request.get_data(as_text=True) au paramètre raw_body.

Gérer le secret de signature

Votre équipe possède un secret préfixé par whsec_. Nous l'utilisons pour signer les webhooks de toutes ses transcriptions.

Vous pouvez afficher ce secret ou le renouveler depuis « Webhooks ».

Le remplacement prend effet immédiatement. Dès lors, chaque webhook est signé avec le nouveau secret.

Réception et nouvelles tentatives

• Répondez avec un statut 2xx pour confirmer la réception.
• Nous considérons l'envoi comme un échec pour tout autre statut, en cas d'erreur de connexion ou sans réponse sous 10 secondes.
• Après un échec, nous réessayons jusqu'à atteindre 6 tentatives au total. Les délais augmentent de façon exponentielle : 2, 4, 8, 16 puis 32 minutes. La dernière tentative intervient environ une heure après la première.
• Fournissez l'URL finale : transcript1 ne suit pas les redirections. Un statut 3xx compte donc comme un échec d'envoi.
• Prévoyez de recevoir plusieurs fois la même notification, notamment si votre serveur répond après le délai maximal. Dédupliquez-la à partir de data.id et de type.