Trascrizione YouTube in Node.js: Fetch Nativo, Nessun npm Install

Non hai bisogno di un pacchetto per questo. Recuperare una trascrizione YouTube in Node.js è una chiamata HTTPS, fetch è globale da Node 18, e l'endpoint parla plain JSON. Tutto in questo articolo viene eseguito in una directory vuota senza package.json — alla fine avrai una funzione transcribe() che restituisce titolo, data di pubblicazione e testo di trascrizione completo per qualsiasi URL YouTube, con gestione degli errori che non indovina.

Il registro npm ha una dozzina di scraper di trascrizioni, e condividono un destino: recuperano da YouTube usando l'IP del tuo server, e YouTube blocca gli IP del datacenter. Un'API ospitata aggira completamente questo.

Il tutto

const KEY = process.env.YT2TEXT_KEY;

async function transcribe(videoUrl, maxChars = 150000) {
  const qs = new URLSearchParams({ url: videoUrl, maxChars: String(maxChars) });
  const res = await fetch(`https://youtube2text.org/api/transcribe?${qs}`, {
    headers: { "x-api-key": KEY },
  });
  const body = await res.json();
  if (!res.ok) {
    const err = new Error(`${body.error.code}: ${body.error.message}`);
    err.code = body.error.code;
    err.retryAfterSeconds = body.error.retryAfterSeconds;
    throw err;
  }
  return body.result;
}

const t = await transcribe("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
console.log(`${t.title} — ${t.contentSize} chars`);
console.log(t.content.slice(0, 300));

Salva come index.mjs (top-level await vuole ESM), esegui node index.mjs. Il parametro url accetta qualsiasi variante di URL YouTube o un ID video nudo di 11 caratteri, e maxChars limita la lunghezza della trascrizione — 150000 è sia il valore predefinito che il limite, quindi riducilo quando il testo sta andando in un prompt LLM.

Non hai ancora una chiave? Afferra quella demo:

curl https://youtube2text.org/api/demo-key

Restituisce {"success":true,"apiKey":"yt_..."}. Nota che è condivisa tra tutti gli utenti anonimi ed è limitata a 5 video al mese per IP — una chiave di prova, non una di produzione.

Gli errori sono JSON, quindi trattali in questo modo

Ogni fallimento ha un campo code stabile. Quelli che meritano un branch:

try {
  await transcribe("https://youtu.be/xxxxxxxxxxx");
} catch (err) {
  switch (err.code) {
    case "RATE_LIMIT_EXCEEDED":
      console.log(`Back off for ${err.retryAfterSeconds}s, then retry`);
      break;
    case "TRANSCRIPT_UNAVAILABLE":
      console.log("Video has no captions — nothing to fetch, skip it");
      break;
    case "VIDEO_NOT_FOUND":
    case "INVALID_URL":
      console.log("Bad input, fix the URL");
      break;
    default:
      throw err; // UNAUTHORIZED, YOUTUBE_ERROR — genuinely unexpected
  }
}

TRANSCRIPT_UNAVAILABLE è l'onesta limitazione dell'intero approccio: le trascrizioni provengono dai tracciamenti didascalici di YouTube, manuali o generati automaticamente, inglese preferito con fallback a qualunque lingua esista. Un video con didascalie disabilitate restituisce un 404 e non c'è nulla da riprovare. Trattalo come un caso normale, non un percorso di eccezione.

TypeScript, se è la tua cosa

La forma della risposta è stabile, quindi un paio di interfacce ti danno piena sicurezza di tipo con zero dipendenze:

interface TranscriptResult {
  videoId: string;
  title: string;
  pubDate: string;
  content: string;
  contentSize: number;
  truncated: boolean;
}

interface ApiError {
  code: string;
  message: string;
  status: number;
  retryAfterSeconds?: number;
}

Digita body come { result: TranscriptResult } | { error: ApiError } e ristretti su res.ok. No any, nessun casting.

In cosa si collega questo

La maggior parte delle persone che lo chiamano da Node sta alimentando trascrizioni a un modello linguistico o a una pipeline di contenuti — trasformare i discorsi in bozze è coperto in Video YouTube in articolo blog, e se il tuo framework di agente parla MCP puoi saltare completamente il livello HTTP con il server MCP per Claude e Codex. Lo stesso endpoint funziona in modo identico da Python se il tuo stack è misto — vedi la versione Python.

Il riferimento completo dei parametri e degli errori vive su youtube2text.org/api.md. È scritto per i computer per leggere, il che come effetto collaterale lo rende misericordiosamente breve anche per gli umani.