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) consumesresidential_requestusage — the fetch routes through the residential proxy. - Non-YouTube transcript retrieval consumes
standard_requestusage (some platforms internally require residential and are billed accordingly).
Pass include_usage=true to receive a usage block disclosing exactly what was charged.
Prerequisites
- A valid VidNavigator API key.
- The Python or JavaScript SDK, version 2.1.0:
pip install vidnavigator==2.1.0Retrieving 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 emptyThe 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.transcriptLong 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:
- Analyze the video for deeper insights.
- Search the video's content with natural language queries.
- Browse every SDK method in the Python and JavaScript references.