SDK per Node.js

Con @transcript1/sdk puoi trascrivere da un server TypeScript o JavaScript. L'SDK crea la trascrizione, carica i file e aspetta che il testo sia pronto.

Per i link dei social serve almeno la versione 1.1.0. La 1.0.1 riconosce solo YouTube e rifiuta gli altri link prima di contattare l'API. Per aggiornare, esegui npm i @transcript1/sdk@latest.

La 1.1.0 copre le sei piattaforme iniziali. Per Twitch, Dailymotion, Pinterest, LinkedIn e Snapchat occorre una release che le includa esplicitamente: un SDK meno recente potrebbe rifiutare quei link senza inviarli all'API.

Installare il pacchetto

npm i @transcript1/sdk

Per eseguire gli esempi con moduli ES, salvali in file .mjs. Se usi .js, aggiungi "type": "module" al package.json. Su Node 20.19+ puoi anche caricare il pacchetto con require(), ad esempio require('@transcript1/sdk').

Configurare la chiave API

Genera una chiave in “API keys” e imposta la variabile d'ambiente TRANSCRIPT1_API_KEY sul server. In alternativa, fornisci apiKey al costruttore:

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

Se non trova una chiave, il costruttore genera un Transcript1Error con codice missing_api_key.

Avviare una trascrizione e aspettare il testo

Chiama transcribe(input, options) per creare la trascrizione e attendere che sia pronta. Ricevi un CompletedTranscription con status: 'completed' e il campo transcript. Se il job non riesce o viene annullato, la promise viene rifiutata.

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

Se passi un Buffer o un Uint8Array, aggiungi il nome del file: serve all'SDK per riconoscere il formato.

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

L'SDK interpreta come link le stringhe che iniziano con http:// o https://; tutte le altre sono percorsi di file. Accetta link di YouTube, X, TikTok, Instagram, Facebook, Bluesky, Twitch, Dailymotion, Pinterest, LinkedIn e Snapchat. Per le piattaforme aggiuntive serve HTTPS. Consulta Link e opzioni di trascrizione per i formati dei link a registrazioni pubbliche, i sottotitoli disponibili e le restrizioni.

Puoi anche caricare file fino a 2.000.000.000 byte, con estensione mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm o mkv.

Usa post pubblici: se contengono più video, trascriviamo solo il primo. Non devi indicare la piattaforma, perché l'API la riconosce dal link. Anche i link brevi ammessi sono elencati in Link e opzioni di trascrizione.

Sono accettati anche Blob, ReadableStream<Uint8Array> e iterabili asincroni di chunk Uint8Array. Per un Blob devi specificare filename, tranne quando è un File con un nome. Per stream e iterabili asincroni, indica sia filename sia size in byte.

Scaricare testo e sottotitoli

Usa download(id, options) per aspettare la trascrizione e riceverla come stringa. Anche scegliendo JSON ottieni una stringa con il JSON dell'API, non un oggetto già deserializzato.

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

Puoi usare timestamps: true solo con text. Negli altri formati, la promise viene rifiutata con invalid_input. La promise di download viene rifiutata anche se il job non riesce o viene annullato.

Avviare il lavoro senza aspettare la trascrizione

Con transcriptions.create puoi inviare il lavoro e tornare al tuo codice prima che il testo sia pronto. Se passi un file, la chiamata aspetta comunque la fine del caricamento.

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

Chiama get senza wait per leggere subito lo stato corrente. Con wait: true, la promise si risolve solo quando lo stato diventa completed, failed o canceled. Controlla quindi finished.status prima di usare il testo. A differenza di transcribe, la promise di get non viene rifiutata solo perché il job non è riuscito o è stato annullato.

Consultare le trascrizioni e l'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);

Durante l'iterazione, list carica le pagine man mano che servono. Puoi filtrare per status o platform, scegliendo tra youtube, x, tiktok, instagram, facebook, bluesky, twitch, dailymotion, pinterest, linkedin, snapchat e upload. Con limit scegli da 1 a 100 elementi per pagina; il valore predefinito dell'API è 20. I campi degli oggetti restano in snake_case, come nell'API. Conserva media_id come stringa opaca, senza interpretarlo.

Se il job è ancora in corso, delete lo annulla. Se è terminato, elimina sia il job sia il testo. Per leggere piano, minuti e limiti, chiama account.

Configurare client e chiamate

Al costruttore puoi passare apiKey, baseUrl, fetch e maxRetries. Se non specifichi baseUrl, il client usa il valore di TRANSCRIPT1_API_URL, quando presente, oppure https://api.transcript1.com. Con fetch fornisci una tua implementazione. Per maxRetries puoi scegliere un intero da 0 a 10; di default è 2.

Queste opzioni valgono sia per transcribe sia per transcriptions.create:

Per transcriptions.get sono disponibili wait, includeWords, onProgress e signal. Aggiungi includeWords: true se vuoi i timestamp delle parole. Durante l'attesa, onProgress ti segnala i cambiamenti.

Per download puoi scegliere format, timestamps e signal; anche list supporta signal. Per usarlo con transcriptions.delete(id, options) o account(options), passa { signal } nell'argomento delle opzioni.

Seguire l'avanzamento

Usa onProgress con transcribe, transcriptions.create oppure transcriptions.get mentre aspetta il completamento:

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

Interrompere una chiamata o fermare il job

Per interrompere una chiamata, passa l'AbortSignal di un AbortController. Se vuoi un timeout, usa AbortSignal.timeout:

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

Se interrompi prima della prima chiamata HTTP, la promise viene rifiutata con aborted e senza ID del job. Se interrompi un caricamento, l'SDK prova prima a eliminare il job, purché sia ancora awaiting_upload. Poi la promise viene rifiutata con aborted e l'ID.

Se interrompi solo l'attesa, il job continua. Recupera transcriptionId dall'errore e riprendi con transcriptions.get(id, { wait: true }). Se vuoi fermare anche il job, devi chiamare transcriptions.delete(id).

Durante l'attesa, l'SDK riprova senza limite dopo errori di rete o risposte HTTP 429, 500, 502, 503 e 504. Prima di riconnettersi aspetta 2, poi 4, 8, 16 e infine 30 secondi. Per le altre chiamate vale maxRetries. Anche la creazione di un job aspetta e riprova se tutti i posti per le trascrizioni attive sono occupati. Usa signal per fissare un limite al tempo totale.

Intercettare gli errori

Gli errori dell'API, dei job e dell'SDK arrivano come Transcript1Error. Intercettalo per leggerne il codice:

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

L'SDK può generare in locale missing_api_key, invalid_input, aborted, network_error o upload_token_refused. Se la risposta di errore non è JSON, il codice segue il formato http_<status>.

Se un job non riesce ma non contiene un oggetto di errore, ricevi transcription_failed. Se invece risulta completato ma manca il testo anche dopo averlo recuperato, la promise di transcribe viene rifiutata con internal_error. Consulta Gestire gli errori per i codici API e gli Endpoint API per i campi delle risposte.

Dove usare l'SDK

Serve Node 20.19+ e l'SDK va usato solo lato server. Bun e Deno dovrebbero funzionare grazie alla compatibilità node:, ma i test automatici vengono eseguiti solo su Node. Non includere mai una chiave API nel codice inviato al browser.