Skip to Content

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 Endpoint

VidNavigator provides a single transcript endpoint for every supported platform, including YouTube. The /transcript endpoint auto-detects the platform from the URL and routes internally.

This replaces the old, separate /youtube/transcript endpoint — YouTube URLs now go through the same /transcript endpoint as everything else. For Instagram, use /transcribe (speech-to-text) instead.

Billing

Billing depends on the URL:

  • YouTube transcript retrieval (or metadata_only: true) consumes residential_request usage — the fetch routes through the residential proxy.
  • Non-YouTube transcript retrieval consumes standard_request usage (some platforms internally require residential and are billed accordingly).

Pass include_usage=true to receive a usage block disclosing exactly what was charged.

Prerequisites

pip install vidnavigator==2.1.0

Retrieving a Transcript

Use get_transcript (Python) or getTranscript (JavaScript) for any platform: YouTube, TikTok, X/Twitter, Facebook, Vimeo, and more.

Retrieving a YouTube Transcript

from vidnavigator import VidNavigatorClient, VidNavigatorError

client = VidNavigatorClient()  # reads VIDNAVIGATOR_API_KEY

try:
    result = client.get_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}")

Pass transcript_text=True (Python) or transcript_text: true (JavaScript) to get the whole transcript as a single string instead of timed segments, and language to request a specific caption language (ISO 639-1, e.g. "fr").

Retrieving Transcripts from Other Platforms

The exact same method works for non-YouTube platforms (TikTok, X/Twitter, Facebook, Vimeo, etc.):

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}")

Getting Metadata Only

If you only need video information without the transcript, use the metadata_only parameter. This is faster and still counts as usage:

# YouTube (metadata_only still routes through the residential proxy → residential_request)
result = client.get_transcript(
    video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    metadata_only=True,
)
print(result.data.video_info.title, result.data.video_info.duration)

# Other platforms → standard_request
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_transcript(
    video_url="https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    fallback_to_metadata=True,
)
# If the transcript is unavailable, you still get video_info,
# but the transcript is 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 speech-to-text, which generates a fresh transcript from the audio.

Speech-to-text supports YouTube, Instagram, X (Twitter), Facebook, TikTok, Dailymotion, Loom, Vimeo, Rumble and Snapchat URLs. On YouTube it transcribes the original audio track.

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)

A common pattern is to try captions first, since they are faster and cheaper, and fall back to speech-to-text:

from vidnavigator import BadRequestError, NotFoundError

def best_transcript(url):
    try:
        return client.get_transcript(video_url=url, transcript_text=True).data.transcript
    except (NotFoundError, BadRequestError):  # no captions, or a platform without captions
        return client.transcribe_video(video_url=url, transcript_text=True).data.transcript

Long Videos (over 10 minutes)

The synchronous /transcribe endpoint accepts media up to 10 minutes; longer media is rejected with 400 video_too_long. The async endpoint POST /transcribe/async has no duration cap.

The 2.1.0 SDKs always use the async endpoint, so transcribe_video / transcribe work on videos of any length with no extra code: they submit the job, poll until it finishes, and return the result. To run many transcriptions in parallel, submit them all first and collect the results afterwards:

urls = [
    "https://www.facebook.com/watch/?v=1234567890",
    "https://vimeo.com/123456789",
]

jobs = [client.submit_transcribe_video(video_url=url) for url in urls]
print([job.task_id for job in jobs])  # save these to resume later with client.resume_job("transcribe", task_id)

for url, job in zip(urls, jobs):
    result = job.result()  # waits until this job is done
    print(url, result.data.transcript[0].text)

See Async Jobs for the raw HTTP workflow, timeouts and webhooks.

Next Steps

Now that you have the transcript, you can:

On this page