Com obtenir la transcripció de YouTube amb una API (curl, Python, JavaScript)

Per obtenir la transcripció de YouTube amb una API, envia una petició HTTP amb l'URL o l'ID del vídeo i una clau d'API, i llegeix la transcripció de la resposta. Aquesta guia mostra la petició en curl, Python i JavaScript amb l'API de transcripcions de sum.video, i després tracta formats, errors i costos.

Què retorna l'API

El punt final retorna els subtítols existents d'un vídeo públic de YouTube, escrits pel creador o generats automàticament per YouTube. No transcriu àudio. Si un vídeo no té subtítols, reps un error en lloc d'una conjectura (més avall).

Els conceptes bàsics:

• Punt final: POST https://sum.video/api/v1/transcript (GET també funciona)
• Autenticació: la teva clau a la capçalera X-API-Key, o Authorization: Bearer <key>
• Entrada: url o video_id
• lang opcional (per defecte en)
• format opcional: json, text o srt

La resposta també indica l'idioma real de la pista de subtítols i si es va generar automàticament, de manera que saps quina qualitat esperar.

Pas 1: Crea una clau d'API

Inicia la sessió i crea una clau al tauler de l'API (/dashboard/api a sum.video). Pots tenir fins a 5 claus actives, cosa útil per separar una clau de proves d'una de producció. La teva primera clau ve amb 10 crèdits gratuïts, prou per a 5 transcripcions, així que pots provar tot el que ve a continuació sense cost.

Pas 2: Fes la primera petició

curl

curl -X POST https://sum.video/api/v1/transcript \
  -H "X-API-Key: $SUMVIDEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "lang": "en", "format": "text"}'

Com que GET també funciona, pots provar-ho des d'un script que només construeixi URL. Millor passar la clau a la capçalera perquè no acabi als registres.

Python

import os
import requests

resp = requests.post(
    "https://sum.video/api/v1/transcript",
    headers={"X-API-Key": os.environ["SUMVIDEO_API_KEY"]},
    json={"video_id": "dQw4w9WgXcQ", "lang": "en", "format": "text"},
    timeout=30,
)

if resp.status_code == 404:
    print("No captions for this video")
else:
    resp.raise_for_status()
    print(resp.text)

JavaScript (Node 18+ o el navegador)

const resp = await fetch("https://sum.video/api/v1/transcript", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.SUMVIDEO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    video_id: "dQw4w9WgXcQ",
    lang: "en",
    format: "text",
  }),
});

if (resp.status === 404) {
  console.log("No captions for this video");
} else if (!resp.ok) {
  throw new Error(`Request failed: ${resp.status}`);
} else {
  console.log(await resp.text());
}

Guarda la clau en un servidor. Una clau al codi del navegador la pot copiar qualsevol persona que obri les eines de desenvolupador.

Pas 3: Tria el format adequat

Si penses enllaçar a un moment del vídeo, fes servir json i construeix l'enllaç a partir de l'offset del segment. Per alimentar un LLM, text és més petit i senzill. Si més endavant vols cercar a mà dins d'una transcripció, mira com cercar dins de la transcripció d'un vídeo de YouTube.

Pas 4: Tria un idioma

lang és en per defecte. Posa-hi l'idioma que vulguis, per exemple de o es. La resposta indica l'idioma de la pista que realment s'ha retornat, així que comprova'l en lloc de suposar-ho. Un vídeo sovint només té una pista de subtítols, i l'API retorna subtítols reals, per tant no els tradueix per tu.

Pas 5: Gestiona els errors

Preveu aquests casos des del primer dia:

• 404 no_transcript: el vídeo no té subtítols, o és una emissió en directe, un vídeo privat o un vídeo eliminat. No hi ha res a reintentar. Salta'l, o demana un altre vídeo a l'usuari.
• 402 budget_exceeded: has arribat al límit mensual de crèdits que vas configurar. Mira la secció següent.
• Límit de freqüència: cada clau permet 60 peticions per minut. Espaia les tasques per lots i redueix el ritme quan et limitin.
• Errors de la nostra banda: reintenta amb una petita espera. No costen res.

Un bucle senzill que reintenti davant d'errors del servidor i salti els 404 cobreix la majoria de necessitats de producció.

Quant costa

Cada transcripció costa 2 crèdits. Les peticions que no retornen cap transcripció o que fallen per part de sum.video no costen res, de manera que un 404 mai no et buida el saldo. Pots consultar el saldo amb GET /api/v1/credits.

Els crèdits es venen en paquets únics que no caduquen mai:

Els subscriptors de Pro també reben 100 crèdits de bonificació cada mes. Per a càrregues més pesades, com ara ingerir un canal sencer, llegeix l'escenari transcripcions de YouTube per a una app RAG a gran escala, que tracta la recàrrega automàtica i els pressupostos. Mira també els preus.

Límits que cal conèixer abans de construir

• Només funcionen els vídeos amb subtítols. És el motiu principal del 404 no_transcript.
• Els subtítols generats automàticament poden tenir errors, sobretot amb noms, accents i termes tècnics.
• L'API només retorna la transcripció. No resumeix. Si vols resums, marques de temps i xat sobre una transcripció, això ho fa el resumidor de YouTube, i l'eina de transcripció és la versió sense codi per a un sol vídeo.
• L'API oficial de YouTube Data no és un substitut aquí. El seu mètode de baixada de subtítols exigeix permís per editar el vídeo, així que està pensat per als teus propis vídeos (documentació de Google).

Fonts

• YouTube Data API: Captions.download
• API de transcripcions de sum.video