Transkripsjoner via YouTube Data API: Hvorfor captions.download feiler

Terminal som viser en 403 Forbidden-respons fra captions.download-endepunktet i YouTube Data API

Prøver du å hente transkripsjoner gjennom YouTube Data API, har du sannsynligvis allerede truffet veggen: captions.list returnerer gladelig ID-er for undertekstspor for enhver video, men i det øyeblikket du kaller captions.download på ett av dem, får du en 403. Du dobbeltsjekker API-nøkkelen, legger til youtube.force-ssl-scopet, prøver OAuth — fortsatt 403. Dette er ikke en bug, og det er ikke et kvoteproblem. Det er med vilje, og dokumentasjonen gjemmer bort poenget.

Begrensningen, presist

captions.download krever et OAuth-token fra en konto som eier videoen. Ikke en hvilken som helst autentisert konto — kanaleieren (eller en innholdsforvalter med rettigheter til den). Captions-endepunktene finnes for at skapere skal kunne administrere undertekstspor på sine egne opplastinger: laste opp en .srt, rette en skrivefeil, slette en dårlig auto-oversettelse. Å laste ned undertekster fra vilkårlige tredjepartsvideoer var aldri en del av kontrakten.

Feilmeldingen sier det rett ut når du leser den nøye:

The permissions associated with the request are not sufficient
to download the caption track.

Så den vanlige eskaleringsstigen — API-nøkkel → OAuth som deg selv → bredere scopes → tjenestekonto — fører ingen steder. Hvert trinn stryker på den samme eierskapssjekken. Jeg brant en ettermiddag på dette før jeg aksepterte det, og å dømme etter trafikken på Stack Overflow har halve internett gjort det samme.

Hva captions.list fortsatt er godt for

For å være rettferdig mot Data API-et: captions.list fungerer med en vanlig API-nøkkel og koster rundt 50 kvoteenheter. Det forteller deg hvilke spor som finnes, språkene deres, og om de er autogenererte (trackKind: "asr") eller menneskeopplastede. Det er genuint nyttig som en forhåndssjekk — hvis en video ikke har noen spor i det hele tatt, vet du på forhånd at du trenger tale-til-tekst i stedet for undertekstuthenting. Data API-et forblir også riktig verktøy for søk, spillelisteopplisting og metadata. Det gir deg bare ikke transkripsjonsteksten.

Alternativ 1: hent undertekster slik spilleren gjør det

Videospilleren mottar åpenbart undertekstdata uten eierens OAuth-token, og biblioteker som youtube-transcript-api (Python) henter dem på samme måte. På laptopen din fungerer dette godt og tar tre linjer.

Forbeholdet dukker opp i produksjon: YouTube utfordrer aggressivt forespørsler fra datasenter-IP-områder. Deploy de samme tre linjene til AWS, GCP eller Heroku, og du begynner å se «Sign in to confirm you're not a bot» og IpBlocked-feil. Jeg har skrevet om den feilmodusen og løsningene separat i hvorfor youtube-transcript-api blir blokkert i skyen — kortversjonen: det kan fikses med residential proxies, men det er et prosjekt i seg selv.

Alternativ 2: et hostet transkripsjons-API

Vil du bare ha tekst ut av en URL, hopper et hostet endepunkt over begge problemene — ingen eierskapskrav, ingen proxy-barnevakt. youtube2text.org kjører undertekst-hentingen bak roterende residential proxies på serversiden, så forespørselen din kan komme fra hvor som helst:

# grab a free demo key (shared, 5 videos/month per IP)
curl -s https://youtube2text.org/api/demo-key

# fetch a transcript
curl -s "https://youtube2text.org/api/transcribe?url=https://www.youtube.com/watch?v=VIDEO_ID" \
  -H "x-api-key: yt_YOUR_KEY"

Responsen er ren JSON:

{"result": {"videoId": "...", "title": "...", "pubDate": "...",
            "content": "full transcript text ...", "contentSize": 12345, "truncated": false}}

Hvis videoen rett og slett ikke har undertekster, får du TRANSCRIPT_UNAVAILABLE med en 404 — samme situasjon som captions.list ville vist som en tom sporliste, bare oppdaget i ett kall i stedet for to.

Det finnes en lengre gjennomgang med feilhåndtering i hent YouTube-transkripsjoner med curl, og en Python-versjon i migreringsguiden for youtube-transcript-api hvis requests-basert kode er mer din stil.

Et fornuftig kombinert oppsett

Det jeg faktisk ville bygget i dag, etter å ha slåss med dette fra begge ender:

Data API for oppdagelse — søk, kanalopplastinger, spillelister, publiseringsdatoer. Det er pålitelig og har raus kvote for metadata.
Et transkripsjonsendepunkt (hostet, eller selvskrapet med proxies hvis du liker sånt) for selve teksten.
Tale-til-tekst som fallback kun for videoer helt uten undertekster.

Å prøve å tvinge captions.download til å gjøre jobben i midten er den ene veien som kategorisk ikke kan fungere for videoer du ikke eier — ingen scope, nøkkel eller konsollinnstilling endrer det.

Vil du ha din egen nøkkel i stedet for den delte demonøkkelen, er innlogging kun med Google på youtube2text.org/app/keys — ikke noe telefonnummer, ikke noe kort. Gratisnivået er 5 videoer/måned; betalte planer starter på $5.99 for 50.