← All guides

Get a YouTube transcript in Python

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

Send video ids to the VidWords API and receive transcript text plus timestamped segments. The example below uses Python’s standard library, so there is no extraction library to install or manage.

Set up your token

Create a VidWords account, get an API token from API keys, and set the VIDWORDS_TOKEN environment variable. Keep the token on your server or local machine; do not commit it or put it in browser code.

Fetch one video or a batch

import json, os, urllib.request

def get_transcripts(video_ids, language=None):
    payload = {"ids": video_ids}
    if language:
        payload["lang"] = language
    request = urllib.request.Request(
        "https://vidwords.com/api/transcripts",
        data=json.dumps(payload).encode(),
        headers={"Authorization": "Basic " + os.environ["VIDWORDS_TOKEN"],
                 "Content-Type": "application/json"},
    )
    with urllib.request.urlopen(request, timeout=120) as response:
        return json.load(response)["results"]

results = get_transcripts(["dQw4w9WgXcQ"])
for result in results:
    if "error" in result:
        print(result["id"], result["error"], result.get("message", ""))
        continue
    print(result["languageCode"], result["text"])
    for segment in result["segments"][:5]:
        print(segment["start"], segment["text"])

Choose a caption language

Omit lang to request the video’s own language, or pass a language code such as en. Inspect languageCode, languageSubstituted and the available-language information in the response. An available caption track can be a translation; check what was actually returned before labelling it.

results = get_transcripts(["dQw4w9WgXcQ"], language="en")

Save results with timestamps

Each segment contains text, start and duration, with times in seconds. Preserve those fields when you need citations or links back to a moment in the video.

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

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.

View full API documentation →