# Transcriberen met de Node.js-SDK

> Transcribeer links en bestanden met @transcript1/sdk vanuit je servercode. Download tekst of ondertitels, volg de voortgang en vang fouten op.

Canonical: https://transcript1.com/nl/docs/sdk
Language: nl
Last updated: 2026-10-16

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

```bash
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”](https://transcript1.com/dashboard/account/tokens). Je kunt die op je server instellen als omgevingsvariabele `TRANSCRIPT1_API_KEY`, of als `apiKey` meegeven aan de constructor:

```javascript
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.

```javascript
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:

```javascript
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](https://transcript1.com/nl/docs/sources-and-options) 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](https://transcript1.com/nl/docs/sources-and-options).

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.

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

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.

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

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

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

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:

| Optie | Wat stel je in? |
|---|---|
| `speakers` | Zet sprekerherkenning aan. |
| `language` | Laat `auto` staan, de standaardwaarde, of geef een ISO 639-1-taalcode mee. |
| `source` | Kies voor links `auto` of `stt`. Bij YouTube, X, TikTok, Bluesky, Dailymotion en LinkedIn kun je ook `captions` kiezen als er een bruikbaar ondertitelspoor is. |
| `fresh` | Maak voor een link een nieuwe transcriptie en hergebruik niet die van de afgelopen 24 uur. |
| `filename` | Geef een bestandsnaam mee voor Buffers, Blobs zonder naam en streams. Je kunt hiermee ook een bestaande bestandsnaam vervangen. |
| `size` | Geef bij streams en async iterables de grootte in bytes mee. Verplicht voor deze invoertypen. |
| `idempotencyKey` | De SDK maakt standaard voor elke aanroep een nieuwe UUID. |
| `onProgress` | Laat voortgangsevents doorgeven aan je callback. |
| `signal` | Geef een AbortSignal mee om de aanroep te kunnen afbreken. |

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:

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

| Eventtype | Wat ontvang je? |
|---|---|
| `upload` | Het aantal verstuurde bytes in `sent` en de totale grootte in `total`. |
| `status` | De huidige jobstatus in `status`. |
| `waiting_slot` | In `retryAfter` staat hoeveel seconden de SDK wacht voordat die opnieuw een plek voor de job probeert te krijgen. |
| `reconnecting` | Geen extra velden. Je ontvangt dit tijdens het wachten één keer per verbindingsonderbreking. |

## 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:

```javascript
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:

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

| Veld | Wat staat erin? |
|---|---|
| `message` | Een uitleg van de fout. |
| `code` | De foutcode van de API of job, `canceled` of een lokale SDK-code. |
| `status` | De HTTP-status. Ontbreekt bij fouten in de job of de lokale SDK. |
| `details` | Extra informatie uit de API-fout, bijvoorbeeld `minutes_needed` of `action_url`. Standaard een leeg object. |
| `retryable` | Of opnieuw proberen zin kan hebben. Staat standaard op false. |
| `transcriptionId` | De id van de job, als die bekend is. |
| `transcription` | Het laatst opgehaalde transcriptieobject, als dat beschikbaar is. |

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](https://transcript1.com/nl/docs/errors). De velden in de response vind je in de [API-referentie](https://transcript1.com/nl/docs/api-reference).

## 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.