Get YouTube Transcript

Extract accurate metadata and transcripts from YouTube videos using residential proxy infrastructure for reliable access.

Overview

This endpoint is specifically designed for YouTube videos. Due to YouTube’s bot detection mechanisms, we use residential proxy infrastructure to ensure reliable transcript extraction.

YouTube transcripts have higher processing costs due to residential proxy requirements. Check the usage costs page for current pricing.

Why a Separate Endpoint?

YouTube has implemented strict bot detection that blocks standard server requests. To maintain reliable access to YouTube transcripts, VidNavigator uses residential proxy infrastructure, which incurs additional costs. This dedicated endpoint allows us to:

Provide reliable, consistent access to YouTube transcripts
Use optimized infrastructure specifically for YouTube
Offer transparent pricing for YouTube-specific usage

For non-YouTube videos (TikTok, X/Twitter, Vimeo, etc.), use the standard /transcript endpoint instead.

Use Cases

Content Analysis

Extract transcripts for AI analysis, sentiment analysis, or content categorization

Search & Discovery

Enable text-based search across YouTube video content

Accessibility

Generate captions and transcripts for accessibility compliance

Content Creation

Create summaries, articles, or repurpose video content

Request Parameters

Parameter	Type	Required	Description
`video_url`	string	Yes	URL of the YouTube video
`language`	string	No	ISO2 language code (e.g., “en”, “es”, “fr”)
`metadata_only`	boolean	No	When `true`, returns only video metadata without fetching the transcript. Uses innertube (no residential proxy needed), counts as regular transcript usage instead of YouTube transcript. Takes precedence over `fallback_to_metadata`.
`fallback_to_metadata`	boolean	No	When `true`, returns video metadata with an empty transcript if transcript is unavailable (returns 200 instead of 404). Ignored if `metadata_only` is `true`.
`transcript_text`	boolean	No	When `true`, returns the transcript as a single plain-text string instead of an array of segments.

Cost-saving tip: Using metadata_only: true bypasses the residential proxy and counts as regular transcript usage, making it more cost-effective when you only need video information.

Example Usage

curl -X POST "https://api.vidnavigator.com/v1/transcript/youtube" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "language": "en"
  }'

Getting Metadata Only (Cost-Effective)

If you only need video metadata without the transcript, use metadata_only: true. This bypasses the residential proxy and counts as regular transcript usage:

curl -X POST "https://api.vidnavigator.com/v1/transcript/youtube" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
    "metadata_only": true
  }'

Using the SDK

from vidnavigator import VidNavigatorClient, VidNavigatorError

client = VidNavigatorClient()

try:
    result = client.get_youtube_transcript(
        video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        language="en"
    )
    print("Video Title:", result.data.video_info.title)
    print("Available Languages:", result.data.video_info.available_languages)
    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}")

Supported URL Formats

This endpoint accepts various YouTube URL formats:

https://youtube.com/watch?v=VIDEO_ID
https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://www.youtube.com/shorts/VIDEO_ID
https://m.youtube.com/watch?v=VIDEO_ID

Troubleshooting

Invalid URL: Ensure the video URL is a valid YouTube URL in one of the supported formats.
Transcript Not Found: Please ensure that the video has subtitles available (either manually added or auto-generated). If no subtitles are present, the transcript cannot be extracted. Consider using fallback_to_metadata: true to get metadata even when transcript is unavailable.
Language Not Supported: Sometimes the selected subtitles language is not available. Check the available_languages field in the response to see which languages are available.
Rate Limit Exceeded: YouTube transcript requests have rate limits. Check your usage and consider upgrading your plan if needed.

If issues persist or you need more help, please reach out to us at [email protected].

Success Response (200 OK)

Returns a video_info object and a transcript object.

{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "channel": "Example Creator",
      "channel_url": "https://www.youtube.com/@ExampleCreator",
      "duration": 212.5,
      "views": 123456789,
      "likes": 987654,
      "published_date": "2009-10-25",
      "keywords": ["example", "youtube", "video"],
      "category": "Music",
      "available_languages": ["en", "es", "fr", "de", "ja"],
      "selected_language": "en"
    },
    "transcript": [
      {
        "text": "We're no strangers to love",
        "start": 0.5,
        "end": 3.2
      },
      {
        "text": "You know the rules and so do I",
        "start": 3.5,
        "end": 5.1
      }
    ]
  }
}

Response with `transcript_text: true`

When you set transcript_text: true, the transcript is returned as a single string:

{
  "status": "success",
  "data": {
    "video_info": { ... },
    "transcript": "We're no strangers to love. You know the rules and so do I."
  }
}

Response with `metadata_only: true`

When you set metadata_only: true, only the video metadata is returned (uses innertube, no residential proxy):

{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
      "url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
      "channel": "Example Creator",
      "channel_url": "https://www.youtube.com/@ExampleCreator",
      "duration": 212.5,
      "views": 123456789,
      "likes": 987654,
      "published_date": "2009-10-25",
      "keywords": ["example", "youtube", "video"],
      "category": "Music",
      "available_languages": ["en", "es", "fr", "de", "ja"]
    }
  }
}

Authorizations

X-API-Key

string

header

required

API key authentication. Include your VidNavigator API key in the X-API-Key header.

Body

application/json

video_url

string<uri>

required

URL of the YouTube video

Example:

"https://youtube.com/watch?v=dQw4w9WgXcQ"

language

string

ISO2 language code (optional)

Required string length: 2

Example:

"en"

metadata_only

boolean

default:false

When true, returns only video metadata without transcript. Uses innertube (no residential proxy), counts as regular transcript usage instead of YouTube transcript.

fallback_to_metadata

boolean

default:false

When true, returns video metadata with an empty transcript if transcript is unavailable (200). Ignored if metadata_only is true.

transcript_text

boolean

default:false

When true, returns the transcript as a single plain-text string instead of an array of segments.

Response

Transcript retrieved successfully

status

enum<string>

Available options:

success

data

object

Show child attributes

API Documentation

Online Videos

Files

System

Overview

Why a Separate Endpoint?

Use Cases

Content Analysis

Search & Discovery

Accessibility

Content Creation

Request Parameters

Example Usage

Getting Metadata Only (Cost-Effective)

Using the SDK

Supported URL Formats

Troubleshooting

Success Response (200 OK)

Response with `transcript_text: true`

Response with `metadata_only: true`

Authorizations

Body

Response

API Documentation

Online Videos

Files

System

​Overview

​Why a Separate Endpoint?

​Use Cases

Content Analysis

Search & Discovery

Accessibility

Content Creation

​Request Parameters

​Example Usage

​Getting Metadata Only (Cost-Effective)

​Using the SDK

​Supported URL Formats

​Troubleshooting

​Success Response (200 OK)

​Response with transcript_text: true

​Response with metadata_only: true

Authorizations

Body

Response

Overview

Why a Separate Endpoint?

Use Cases

Request Parameters

Example Usage

Getting Metadata Only (Cost-Effective)

Using the SDK

Supported URL Formats

Troubleshooting

Success Response (200 OK)

Response with `transcript_text: true`

Response with `metadata_only: true`