Transcriberen met de Node.js-SDK

Met @transcript1/sdk transcribeer je vanuit TypeScript of JavaScript op je server. De SDK regelt het aanmaken, uploaden en wachten op het transcript.

Voor de oorspronkelijke zes platforms heb je SDK 1.1.0 of nieuwer nodig. SDK 1.0.1 herkent alleen YouTube-links en weigert de andere links al voordat ze naar de API gaan. Werk bij met npm i @transcript1/sdk@latest.

Voor Twitch, Dailymotion, Pinterest, LinkedIn en Snapchat heb je een release nodig waarin die platforms zijn toegevoegd. De basisversie voor de zes oorspronkelijke platforms is daarvoor niet genoeg; oudere clients kunnen de links lokaal weigeren.

Installeer het pakket

npm i @transcript1/sdk

De voorbeelden hieronder zijn ES-modules. Gebruik daarvoor .mjs-bestanden of zet "type": "module" in package.json als je .js gebruikt. Op Node 20.19+ kun je ook require() gebruiken, bijvoorbeeld require('@transcript1/sdk').

Stel je API-sleutel in

Maak een sleutel aan op “API keys”. Je kunt die op je server instellen als omgevingsvariabele TRANSCRIPT1_API_KEY, of als apiKey meegeven aan de constructor:

import { Transcript1 } from '@transcript1/sdk';
 
const t1 = new Transcript1(); // reads TRANSCRIPT1_API_KEY
const other = new Transcript1({ apiKey: 't1_...' });

Ontbreekt de sleutel, dan gooit de constructor een Transcript1Error met code missing_api_key.

Start een transcriptie en wacht op de tekst

Met transcribe(input, options) start je een job en wacht je op de tekst. Je krijgt een CompletedTranscription met status: 'completed' en het veld transcript terug. Mislukt de job of annuleer je die, dan wordt de promise afgewezen.

const done = await t1.transcribe('https://youtu.be/dQw4w9WgXcQ');
console.log(done.transcript.text);
 
const file = await t1.transcribe('./interview.m4a', { speakers: true });

Geef je een Buffer of Uint8Array mee, voeg dan ook de bestandsnaam toe. De SDK gebruikt die om het mediatype te herkennen:

import { readFile } from 'node:fs/promises';
 
const buffer = await readFile('./call.mp3');
const call = await t1.transcribe(buffer, { filename: 'call.mp3' });

Begint een string met http:// of https://, dan behandelt de SDK die als een link. Elke andere string is een bestandspad. Je kunt links gebruiken van YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn en Snapchat. In Bronnen en instellingen vind je de toegestane openbare opnames, ondertitelondersteuning en beperkingen. Voor de extra platforms is HTTPS verplicht.

Je kunt ook bestanden uploaden: mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm of mkv, tot maximaal 2.000.000.000 bytes.

Zorg dat de post openbaar is. Staan er meerdere video’s in, dan transcriberen we alleen de eerste. Het platform hoef je niet op te geven; de API herkent het aan de link. Welke korte links werken en welke limieten gelden, staat in Bronnen en instellingen.

Een Blob, ReadableStream<Uint8Array> of async iterable met Uint8Array-chunks werkt ook. Geef bij een Blob filename mee, behalve als je een File met een naam gebruikt. Bij streams en async iterables moet je zowel filename als size in bytes opgeven.

Download tekst of ondertitels

Met download(id, options) wacht je op de transcriptie en krijg je de tekst als string. Ook bij JSON krijg je een string met de JSON-response van de API, niet een al geparseerd object.

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

Gebruik timestamps: true alleen met text. Kies je een ander formaat, dan wordt de promise afgewezen met invalid_input. Als de job mislukt of je die annuleert, wordt de promise van download ook afgewezen.

Start een job zonder op de tekst te wachten

Wil je niet op de tekst wachten, gebruik dan transcriptions.create. Bij een bestand wacht deze aanroep wel tot de upload klaar is.

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

Met get haal je de transcriptie op zoals die er nu voor staat. Geef je wait: true mee, dan krijg je die pas terug zodra de job completed, failed of canceled bereikt. Controleer dus finished.status voordat je de tekst leest. Anders dan bij transcribe wordt de promise van get niet afgewezen als de job mislukt of je die annuleert.

Bekijk je transcripties en account

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

Tijdens het doorlopen haalt list zelf de volgende pagina op. Je kunt filteren op status of platform (youtube, x, tiktok, instagram, facebook, bluesky, twitch, dailymotion, pinterest, linkedin, snapchat of upload). Met limit kies je de paginagrootte: 1 tot 100, standaard 20 in de API. De objecten houden hun snake_case-veldnamen. Bewaar media_id als string en leid er zelf niets uit af.

Loopt een job nog, dan annuleert delete die. Is die al afgerond, dan verwijdert delete de job en het transcript. Met account vraag je je abonnement, minuten en limieten op.

Stel de SDK in

Aan de constructor kun je apiKey, baseUrl, fetch en maxRetries meegeven. Voor baseUrl gebruikt de SDK standaard TRANSCRIPT1_API_URL als je die hebt ingesteld, anders https://api.transcript1.com. Met fetch geef je een eigen implementatie door. maxRetries staat standaard op 2; je kunt een geheel getal van 0 tot 10 kiezen.

Voor zowel transcribe als transcriptions.create kun je deze opties gebruiken:

Bij transcriptions.get kun je wait, includeWords, onProgress en signal meegeven. Met includeWords: true vraag je tijdstempels per woord op. onProgress houdt je tijdens het wachten op de hoogte van wijzigingen.

Voor download zijn er format, timestamps en signal. Ook list ondersteunt signal. Aan transcriptions.delete(id, options) en account(options) geef je het door als { signal } in het opties-argument.

Volg de voortgang

Gebruik onProgress bij transcribe, transcriptions.create of transcriptions.get wanneer die wacht:

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

Breek een aanroep af

Wil je een aanroep kunnen afbreken, geef dan een AbortSignal van een AbortController mee. Met AbortSignal.timeout stel je een maximale wachttijd in:

await t1.transcribe('https://youtu.be/dQw4w9WgXcQ', {
  signal: AbortSignal.timeout(10 * 60_000),
});

Breek je af vóór het eerste request, dan wordt de promise afgewezen met aborted, zonder job-id. Tijdens een upload probeert de SDK eerst de job te verwijderen als die nog op awaiting_upload staat. Daarna wordt de promise afgewezen met aborted en de id.

Breek je alleen het wachten af, dan loopt de job door. Gebruik de transcriptionId uit de fout om verder te wachten met transcriptions.get(id, { wait: true }). Wil je ook de job stoppen, roep dan transcriptions.delete(id) aan.

Valt tijdens het wachten de verbinding weg, of krijgt de SDK HTTP 429, 500, 502, 503 of 504, dan probeert die het onbeperkt opnieuw. Tussen verbindingspogingen wacht de SDK eerst 2 seconden, daarna 4, 8, 16 en vervolgens 30 seconden. Voor andere requests geldt maxRetries. Ook bij het aanmaken wacht de SDK en probeert die het opnieuw als alle plekken voor actieve jobs bezet zijn. Begrens de totale duur met signal.

Vang fouten op

Vang Transcript1Error af voor fouten uit de API, de transcriptie of de SDK zelf:

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

De SDK gebruikt lokaal de codes missing_api_key, invalid_input, aborted, network_error en upload_token_refused. Komt een foutresponse niet als JSON terug, dan krijg je http_<status>.

Ontbreekt het foutobject bij een mislukte job, dan krijg je transcription_failed. Is de job klaar, maar ontbreekt na het ophalen het transcript, dan wordt de promise van transcribe afgewezen met internal_error. De API-codes staan bij Fouten afhandelen. De velden in de response vind je in de API-referentie.

Waar kun je de SDK draaien?

Gebruik Node 20.19+ en draai de SDK alleen op je server. Stuur nooit een API-sleutel naar de browser. Bun en Deno zouden via hun node:-compatibiliteit ook moeten werken, maar de automatische tests draaien alleen op Node.