> ## 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.

# Getting Transcripts

> Learn how to retrieve transcripts from online videos using the VidNavigator API and SDKs.

## 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:

<CardGroup cols={2}>
  <Card title="YouTube Videos" icon="youtube" href="/api-reference/endpoint/transcript-youtube">
    Use `/youtube/transcript` for YouTube videos. This endpoint uses residential proxy infrastructure for reliable access.
  </Card>

  <Card title="Other Platforms" icon="video" href="/api-reference/endpoint/transcript">
    Use `/transcript` for TikTok, X/Twitter, Facebook, Vimeo, Dailymotion, Loom, and other platforms.
  </Card>
</CardGroup>

<Note>
  **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.
</Note>

## 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

```python theme={null}
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

```javascript theme={null}
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

```python theme={null}
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

```javascript theme={null}
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:

```python theme={null}
# 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:

```python theme={null}
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
```

<Note>
  The `metadata_only` parameter takes precedence over `fallback_to_metadata`. If both are set, only metadata will be returned.
</Note>

## 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.

<Alert>
  The **/transcribe** endpoint supports **Instagram, X (Twitter), Facebook, TikTok, Dailymotion, Loom, and Vimeo** URLs. YouTube videos should use the `/youtube/transcript` endpoint instead.
</Alert>

### Python SDK – `transcribe_video`

```python theme={null}
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`

```javascript theme={null}
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:

* [Analyze the video](/guides/analyzing-videos) for deeper insights.
* [Search the video's content](/guides/searching-videos) with natural language queries.