← All guides

Get YouTube transcripts in Google Colab

Written by the VidWords Team · · Updated · Report a correction

Use a hosted transcript API when you want to work with video text in a notebook. A RequestBlocked error from an extraction library describes a refused request; it does not establish that the video has no transcript. Check the video and error before repeatedly restarting the notebook.

Keep your token outside the notebook

Create a secret named VIDWORDS_TOKEN in Colab’s Secrets panel and allow the notebook to access it. Notebook cells and outputs are easy to share, so do not paste credentials into them or print a secret while troubleshooting.

Request a transcript

This cell reads the token from Colab Secrets, sends one video id, and inspects each returned result.

import json, urllib.request
from google.colab import userdata

request = urllib.request.Request(
    "https://vidwords.com/api/transcripts",
    data=json.dumps({"ids": ["dQw4w9WgXcQ"]}).encode(),
    headers={"Authorization": "Basic " + userdata.get("VIDWORDS_TOKEN"),
             "Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=120) as response:
    results = json.load(response)["results"]

for result in results:
    if "error" in result:
        print(result["id"], result["error"])
    else:
        print(result["text"][:1000])

Save the result before the session ends

A notebook runtime can be reset. Save successful results as JSON and download the file or put it in your own persistent storage. Keep the segment timestamps if your research needs citations.

with open("transcripts.json", "w", encoding="utf-8") as output:
    json.dump(results, output, ensure_ascii=False, indent=2)

For a one-off task

You can also open a video in VidWords, export its transcript, and load that file into the notebook. That may be simpler than adding an API integration for a single video.

Limits and failed lookups

The REST API accepts up to 50 video ids per call. A delivered caption transcript uses one Cloud Request. A free account includes 100 one-time Developer Requests; see current plans and top-ups for continued use. Audio transcription requires separate AI Units and explicit consent through the API’s allowAsr option.

Read each result’s error field: one unavailable video does not make the rest of a batch fail. A lookup that returns no transcript is not charged. Hosted retrieval can still be refused by YouTube; it does not promise access to private, restricted or unavailable videos. See the API reference for response fields and limits.

Read the API docs →