SDK Node.js

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

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 ». Sur votre serveur, définissez la variable TRANSCRIPT1_API_KEY, ou fournissez la clé au constructeur avec apiKey :

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.

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 :

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 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 pour les liens courts et les limites.

Le SDK accepte aussi un Blob, un ReadableStream<Uint8Array> 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.

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.

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

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 :

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 :

await t1.transcribe('./interview.m4a', {
  onProgress(event) {
    console.log(event);
  },
});

Annuler un appel

Pour interrompre un appel, transmettez l'AbortSignal d'un AbortController. Pour limiter sa durée, utilisez AbortSignal.timeout :

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 :

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);
  }
}

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_<status>.

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 détaille les codes de l'API ; la documentation API 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.