← All guides

YouTube transcripts on Render and Railway

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

A script that works locally may encounter refused requests after deployment. First record the returned error and check the video’s caption availability. Redeploying repeatedly does not establish which of those problems you have.

Use a server-side integration

Set VIDWORDS_TOKEN as a secret environment variable in your hosting dashboard. Keep the request in your backend; a browser bundle must never contain the token. The following JavaScript uses the built-in fetch available in current Node.js runtimes.

const response = await fetch("https://vidwords.com/api/transcripts", {
  method: "POST",
  headers: {
    Authorization: `Basic ${process.env.VIDWORDS_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ ids: ["dQw4w9WgXcQ"] }),
  signal: AbortSignal.timeout(120000),
});
if (!response.ok) throw new Error(`Transcript request failed: ${response.status}`);
const { results } = await response.json();
for (const result of results) {
  if (result.error) console.error(result.id, result.error, result.message);
  else console.log(result.id, result.text);
}

Keep the failure visible to the reader

Return a useful message when a video has no available transcript. Distinguish that from an authentication error, an exhausted balance or a temporary service failure. Store completed results in your application so a page refresh does not start the same work again.

Check the deployed environment

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 →