YouTube transcripts on Render and Railway
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
- Confirm the token is configured for the service handling the request.
- Confirm your application can reach the API over HTTPS.
- Set a request deadline appropriate to the user experience, and handle a deadline explicitly.
- Test one video before submitting a larger batch.
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.