# SDK Node.js > Transcrivez des vidéos en ligne et vos fichiers locaux côté serveur avec @transcript1/sdk. Récupérez le texte ou les sous-titres, suivez la progression et gérez les erreurs. Canonical: https://transcript1.com/fr/docs/sdk Language: fr Last updated: 2026-10-16 Avec `@transcript1/sdk`, votre serveur TypeScript ou JavaScript peut envoyer un fichier, lancer une transcription et attendre que le texte soit prêt. Les liens des réseaux sociaux demandent au minimum le SDK 1.1.0. La version 1.0.1 accepte seulement YouTube et refuse les autres liens avant l'appel API. Mettez-la à jour avec `npm i @transcript1/sdk@latest`. La version 1.1.0 couvre les six plateformes d'origine. Pour Twitch, Dailymotion, Pinterest, LinkedIn et Snapchat, utilisez une version qui intègre ces plateformes. Une ancienne version peut refuser leurs liens sans contacter le serveur. ## Installation ```bash npm i @transcript1/sdk ``` Les exemples ci-dessous utilisent les modules ES. Vous pouvez les enregistrer en `.mjs` ou, pour des fichiers `.js`, ajouter `"type": "module"` à `package.json`. À partir de Node 20.19+, vous pouvez aussi utiliser `require()`, par exemple `require('@transcript1/sdk')`. ## Clé API Récupérez une clé dans [« API keys »](https://transcript1.com/dashboard/account/tokens). Sur votre serveur, définissez la variable `TRANSCRIPT1_API_KEY`, ou fournissez la clé au constructeur avec `apiKey` : ```javascript import { Transcript1 } from '@transcript1/sdk'; const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY const other = new Transcript1({ apiKey: 't1_...' }); ``` Si aucune clé n'est disponible, le constructeur lève `Transcript1Error` avec le code `missing_api_key`. ## Lancer une transcription et attendre le texte Appelez `transcribe(input, options)` pour créer la transcription et attendre la fin du traitement. Vous obtenez un objet `CompletedTranscription` avec `status: 'completed'`. Son champ `transcript` contient la transcription. Si le traitement échoue ou si vous l'annulez, la promesse est rejetée. ```javascript const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ'); console.log(done.transcript.text); const file = await t1.transcribe('./interview.m4a', { speakers: true }); ``` Avec un Buffer ou un Uint8Array, indiquez aussi le nom du fichier. Le SDK s'en sert pour reconnaître le type de média : ```javascript import { readFile } from 'node:fs/promises'; const buffer = await readFile('./call.mp3'); const call = await t1.transcribe(buffer, { filename: 'call.mp3' }); ``` Le SDK reconnaît comme lien toute chaîne commençant par `http://` ou `https://`. Pour les autres chaînes, il cherche un fichier local. Il accepte les liens YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn et Snapchat, ainsi que les fichiers importés. Twitch, Dailymotion, Pinterest, LinkedIn et Snapchat exigent HTTPS. La page [Sources et options](https://transcript1.com/fr/docs/sources-and-options) précise quels enregistrements publics sont acceptés, où les sous-titres sont disponibles et quelles restrictions s'appliquent. Pour un fichier, la limite est de 2 000 000 000 octets. Extensions acceptées : mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm et mkv. Le post doit être public. S'il contient plusieurs vidéos, nous transcrivons uniquement la première. Vous n'avez pas à préciser la plateforme : l'API la reconnaît dans le lien. Consultez [Sources et options](https://transcript1.com/fr/docs/sources-and-options) pour les liens courts et les limites. Le SDK accepte aussi un Blob, un `ReadableStream` ou un itérable asynchrone de blocs Uint8Array. Fournissez `filename` pour un Blob, sauf s'il s'agit d'un File qui possède déjà un nom. Pour un flux ou un itérable asynchrone, fournissez à la fois `filename` et `size`, en octets. ## Télécharger le texte ou les sous-titres Avec `download(id, options)`, vous récupérez une chaîne de caractères une fois le traitement terminé. Même en format JSON, la méthode renvoie le texte JSON de l'API : elle ne le convertit pas en objet JavaScript. ```javascript const text = await t1.download(done.id); // text is the default const withTimes = await t1.download(done.id, { timestamps: true }); const srt = await t1.download(done.id, { format: 'srt' }); const vtt = await t1.download(done.id, { format: 'vtt' }); const json = await t1.download(done.id, { format: 'json' }); ``` L'option `timestamps: true` est réservée au format `text`. Avec un autre format, la promesse est rejetée avec `invalid_input`. Elle est également rejetée si la transcription échoue ou si vous l'annulez. ## Lancer le traitement sans attendre Pour lancer une transcription et reprendre aussitôt votre code, utilisez `transcriptions.create`. Si vous envoyez un fichier, la méthode attend tout de même la fin de son import avant de rendre la main. ```javascript const job = await t1.transcriptions.create('./long-interview.mp4'); const now = await t1.transcriptions.get(job.id); const finished = await t1.transcriptions.get(job.id, { wait: true }); ``` Vous pouvez consulter l'état courant avec `get`, sans `wait`. Ajoutez `wait: true` pour attendre un statut final : `completed`, `failed` ou `canceled`. Lisez donc `finished.status` avant d'accéder au texte. À la différence de `transcribe`, `get` résout la promesse même si la transcription a échoué ou a été annulée. ## Gérer les transcriptions et consulter le compte ```javascript for await (const item of t1.transcriptions.list({ status: 'completed', limit: 50 })) { console.log(item.id, item.created_at); } await t1.transcriptions.delete(job.id); const account = await t1.account(); console.log(account.minutes.remaining); ``` La boucle sur `list` récupère les pages au fur et à mesure. Vous pouvez filtrer par `status` ou par `platform` : `youtube`, `x`, `tiktok`, `instagram`, `facebook`, `bluesky`, `twitch`, `dailymotion`, `pinterest`, `linkedin`, `snapchat` ou `upload`. Réglez la taille des pages avec `limit`, de 1 à 100 ; l'API utilise 20 par défaut. Les champs gardent les noms en `snake_case` de l'API. Considérez `media_id` comme une chaîne opaque, sans chercher à en interpréter le contenu. Appelez `delete` pour annuler un traitement en cours ou supprimer une transcription terminée avec son texte. Pour connaître votre offre, votre solde de minutes et vos limites, appelez `account`. ## Options Vous pouvez configurer `apiKey`, `baseUrl`, `fetch` et `maxRetries` dans le constructeur. Pour `baseUrl`, le SDK utilise `TRANSCRIPT1_API_URL` si cette variable est définie, sinon `https://api.transcript1.com`. L'option `fetch` permet de fournir votre propre implémentation. Avec `maxRetries`, choisissez un entier de 0 à 10 ; la valeur par défaut est 2. Les options suivantes s'utilisent avec `transcribe` comme avec `transcriptions.create` : | Option | Utilisation | |---|---| | `speakers` | Active l'identification des locuteurs. | | `language` | Indiquez un code de langue ISO 639-1, ou laissez `auto` (valeur par défaut). | | `source` | Pour un lien, choisissez `auto` ou `stt`. YouTube, X, TikTok, Bluesky, Dailymotion et LinkedIn acceptent aussi `captions` (sous-titres uniquement) si une piste est exploitable. | | `fresh` | Pour un lien, lance un nouveau traitement au lieu de réutiliser la transcription des dernières 24 heures. | | `filename` | Indique le nom du fichier. Obligatoire pour un Buffer, un Blob sans nom ou un flux ; permet aussi de remplacer le nom d'un fichier. | | `size` | Indique la taille en octets. Obligatoire pour les flux et les itérables asynchrones. | | `idempotencyKey` | Le SDK génère un nouvel UUID à chaque appel si vous ne fournissez pas de clé. | | `onProgress` | Fonction appelée pour suivre la progression. | | `signal` | Fournissez un AbortSignal pour pouvoir annuler l'appel. | Pour `transcriptions.get`, les options sont `wait`, `includeWords`, `onProgress` et `signal`. Demandez `includeWords: true` pour obtenir l'horodatage par mot. Pendant l'attente, `onProgress` vous informe des changements. Sur `download`, vous pouvez passer `format`, `timestamps` et `signal`. Sur `list`, vous pouvez aussi passer `signal`. Pour `transcriptions.delete(id, options)` et `account(options)`, utilisez l'argument d'options `{ signal }`. ## Suivre la progression Ajoutez une fonction `onProgress` à `transcribe`, à `transcriptions.create` ou à `transcriptions.get` lorsque cet appel attend la fin du traitement : ```javascript await t1.transcribe('./interview.m4a', { onProgress(event) { console.log(event); }, }); ``` | Type d'événement | Informations reçues | |---|---| | `upload` | `sent` et `total` indiquent les octets envoyés et le total. | | `status` | `status` indique l'état courant du traitement. | | `waiting_slot` | `retryAfter` donne le délai en secondes avant la prochaine tentative de lancement, en attendant qu'une place se libère. | | `reconnecting` | Aucun champ en plus. Vous recevez cet événement une fois par coupure de connexion pendant l'attente. | ## Annuler un appel Pour interrompre un appel, transmettez l'`AbortSignal` d'un AbortController. Pour limiter sa durée, utilisez `AbortSignal.timeout` : ```javascript await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', { signal: AbortSignal.timeout(10 * 60_000), }); ``` Si vous annulez avant le premier appel API, la promesse est rejetée avec `aborted`, sans identifiant de transcription. Pendant l'import, le SDK essaie d'abord de supprimer la transcription si son statut est encore `awaiting_upload`. La promesse est ensuite rejetée avec `aborted` et son identifiant. Si vous interrompez seulement l'attente, la transcription continue sur le serveur. Récupérez `transcriptionId` dans l'erreur pour reprendre avec `transcriptions.get(id, { wait: true })`. Pour arrêter le traitement lui-même, appelez `transcriptions.delete(id)`. Pendant l'attente, le SDK réessaie sans limite en cas d'erreur réseau ou de réponse HTTP 429, 500, 502, 503 ou 504. Il attend 2 secondes avant de se reconnecter, puis 4, 8, 16 et enfin 30 secondes. Pour les autres appels, il respecte `maxRetries`. Si la limite de transcriptions actives est atteinte, la création attend une place et réessaie. Utilisez `signal` pour fixer une durée totale maximale. ## Erreurs Interceptez `Transcript1Error` pour distinguer les erreurs de l'API, les échecs de transcription et les erreurs du SDK : ```javascript import { Transcript1Error } from '@transcript1/sdk'; try { await t1.transcribe('./call.mp3'); } catch (error) { if (error instanceof Transcript1Error) { console.error(error.code, error.message, error.transcriptionId); } } ``` | Champ | Contenu | |---|---| | `message` | Texte qui décrit l'erreur. | | `code` | Code renvoyé par l'API ou le traitement, `canceled`, ou code local du SDK. | | `status` | Statut HTTP. Absent pour un échec de transcription ou une erreur locale. | | `details` | Précisions de l'API, par exemple `minutes_needed` ou `action_url`. Objet vide par défaut. | | `retryable` | Vaut `true` si réessayer peut aider, et `false` par défaut. | | `transcriptionId` | Identifiant de transcription, si le SDK le connaît. | | `transcription` | Dernier objet de transcription reçu, s'il est disponible. | Le SDK utilise les codes locaux `missing_api_key`, `invalid_input`, `aborted`, `network_error` et `upload_token_refused`. S'il reçoit une réponse d'erreur qui n'est pas en JSON, le code prend la forme `http_`. Si le traitement échoue sans objet d'erreur, le SDK utilise `transcription_failed`. Si le traitement est terminé mais que le texte manque encore après récupération, la promesse de `transcribe` est rejetée avec `internal_error`. La page [Erreurs](https://transcript1.com/fr/docs/errors) détaille les codes de l'API ; la [documentation API](https://transcript1.com/fr/docs/api-reference) décrit les champs des réponses. ## Environnements d'exécution Utilisez Node 20.19+ côté serveur. Bun et Deno devraient aussi fonctionner grâce à leur compatibilité `node:`, mais les tests automatisés couvrent uniquement Node. Ne chargez pas le SDK côté navigateur : votre clé API doit rester sur le serveur.