← All guides

TranscriptsDisabled: missing captions and what to do next

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

TranscriptsDisabled means the library could not offer a caption transcript for the request. Check the video on YouTube before concluding the creator deliberately turned captions off: the video may never have had captions, or caption availability may differ from what the tool reports.

Check the video and language

  1. Open the video on YouTube and look for its transcript or caption language list.
  2. If captions exist, verify the language you requested. A missing language is different from a video with no captions.
  3. If the tool reports a blocked request, treat that as a retrieval failure. Do not label it “no captions.”
  4. If no captions exist, decide whether you need an audio transcription instead.

Read the result your application receives

With the VidWords API, inspect every item’s error and message. Keep the requested id with the result so a single unavailable video does not interrupt 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"]

for result in get_transcripts(["dQw4w9WgXcQ"]):
    if "error" in result:
        print("Unavailable:", result["id"], result["error"])
    else:
        print(result["languageCode"], result["text"])

When the video has no captions

Audio transcription creates text from speech and is a separate action from reading existing captions. In VidWords it requires a paid plan or purchased AI Units. In the API, allowAsr: true explicitly permits that work; leave it unset when you want captions only. Check the quoted cost and limits before opting in.

Audio transcription still requires access to the video’s audio. It cannot recover a private, unavailable or otherwise inaccessible 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.