Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vidnavigator.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

VidNavigator is the ultimate video to text solution for extracting subtitles and captions from online videos, giving you all the essential information at your fingertips! Need full transcripts, timestamps, or video metadata? We’ve got it all. The JSON output is ready for instant integration into AI-powered applications.

​
Transcript Endpoints

VidNavigator provides different endpoints for different video platforms:

YouTube Videos

Use /youtube/transcript for YouTube videos. This endpoint uses residential proxy infrastructure for reliable access.

Other Platforms

Use /transcript for TikTok, X/Twitter, Facebook, Vimeo, Dailymotion, Loom, and other platforms.
Why separate endpoints? YouTube has implemented strict bot detection that requires residential proxy infrastructure to bypass. This dedicated endpoint allows transparent residential_request billing and optimized infrastructure.

​
Billing

Non-YouTube transcript retrieval consumes standard_request usage. YouTube transcript retrieval consumes residential_request usage unless metadata_only: true bypasses the residential proxy.

​
Prerequisites

  • A valid VidNavigator API key.
  • The Python or JavaScript SDK installed in your project.

​
Retrieving a YouTube Transcript

​
Using the Python SDK

from vidnavigator import VidNavigatorClient, VidNavigatorError

client = VidNavigatorClient()

try:
    result = client.get_youtube_transcript(
        video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    )
    print("Video Title:", result.data.video_info.title)
    print("Available Languages:", result.data.video_info.available_languages)
    # Each item in the transcript is a segment with text, start, and end times
    for segment in result.data.transcript:
        print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")
except VidNavigatorError as e:
    print(f"An error occurred: {e.message}")

​
Using the JavaScript SDK

const { VidNavigatorClient, VidNavigatorError } = require('vidnavigator');

const client = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY,
});

async function getYouTubeTranscript() {
  try {
    const { video_info, transcript } = await client.getYouTubeTranscript({
      video_url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    });
    console.log("Video Title:", video_info.title);
    console.log("Available Languages:", video_info.available_languages);
    // Each item in the transcript is an object with text, start, and end properties
    transcript.forEach(segment => {
      console.log(`[${segment.start.toFixed(2)}s - ${segment.end.toFixed(2)}s] ${segment.text}`);
    });
  } catch (error) {
    if (error instanceof VidNavigatorError) {
      console.error(`An error occurred: ${error.message}`);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
}

getYouTubeTranscript();

​
Retrieving Transcripts from Other Platforms

For non-YouTube platforms (TikTok, X/Twitter, Facebook, Vimeo, etc.), use the standard transcript endpoint:

​
Using the Python SDK

from vidnavigator import VidNavigatorClient, VidNavigatorError

client = VidNavigatorClient()

try:
    result = client.get_transcript(
        video_url="https://twitter.com/user/status/123456789"
    )
    print("Video Title:", result.data.video_info.title)
    for segment in result.data.transcript:
        print(f"[{segment.start:.2f}s - {segment.end:.2f}s] {segment.text}")
except VidNavigatorError as e:
    print(f"An error occurred: {e.message}")

​
Using the JavaScript SDK

const { VidNavigatorClient, VidNavigatorError } = require('vidnavigator');

const client = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY,
});

async function getTranscript() {
  try {
    const { video_info, transcript } = await client.getTranscript({
      video_url: "https://twitter.com/user/status/123456789"
    });
    console.log("Video Title:", video_info.title);
    transcript.forEach(segment => {
      console.log(`[${segment.start.toFixed(2)}s - ${segment.end.toFixed(2)}s] ${segment.text}`);
    });
  } catch (error) {
    if (error instanceof VidNavigatorError) {
      console.error(`An error occurred: ${error.message}`);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
}

getTranscript();

​
Getting Metadata Only

If you only need video information without the transcript, use the metadata_only parameter. This is faster and, for YouTube, bypasses the residential proxy so it counts as standard_request usage instead of residential_request usage: 
# YouTube
result = client.get_youtube_transcript(
    video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    metadata_only=True
)

# Other platforms
result = client.get_transcript(
    video_url="https://twitter.com/user/status/123456789",
    metadata_only=True
)

​
Graceful Fallback to Metadata

If you want to get metadata even when a transcript isn’t available (instead of receiving a 404 error), use the fallback_to_metadata parameter: 
result = client.get_youtube_transcript(
    video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    fallback_to_metadata=True
)

# If transcript is unavailable, you'll still get video_info
# but transcript will be empty
The metadata_only parameter takes precedence over fallback_to_metadata. If both are set, only metadata will be returned.

​
When a Transcript Isn’t Available

Sometimes a platform doesn’t expose captions we can fetch directly (e.g., many Instagram Reels). In that case, the transcript endpoint will return an error such as 404 transcript_not_available. When this happens you can fall back to the /transcribe endpoint, which runs speech-to-text to generate a fresh transcript.

​
Python SDK – transcribe_video

from vidnavigator import VidNavigatorClient

client = VidNavigatorClient()

result = client.transcribe_video(
    video_url="https://www.instagram.com/reel/C86ZvEaqRmo/"
)
print("Transcript length:", len(result.data.transcript))
print("First line:", result.data.transcript[0].text)

​
JavaScript SDK – transcribeVideo

const { VidNavigatorClient } = require('vidnavigator');

const client = new VidNavigatorClient({
  apiKey: process.env.VIDNAVIGATOR_API_KEY,
});

async function transcribe() {
  const { transcript } = await client.transcribeVideo({
    video_url: "https://www.instagram.com/reel/C86ZvEaqRmo/",
  });
  console.log(`Transcript has ${transcript.length} segments`);
  console.log("First line:", transcript[0].text);
}

transcribe();

​
Next Steps

Now that you have the transcript, you can: