Skip to Content

Get Video Transcript

Extract transcript from any supported online video (YouTube, Vimeo, Twitter/X, TikTok, Facebook, Dailymotion, Loom, Snapchat, etc.) with optional language selection. The endpoint auto-detects the platform from the URL and routes internally.

Note: for Instagram videos, use /transcribe instead (speech-to-text).

Options:

  • transcript_text=true: Returns the transcript as a single plain-text string instead of an array of segments.
  • metadata_only=true: Returns only video metadata (no transcript).
  • fallback_to_metadata=true: If transcript is unavailable, returns video metadata with an empty transcript instead of a 404 error (ignored when metadata_only=true).

Set include_usage=true to receive the usage block in the response.

POST
/transcript

Extract accurate metadata and transcripts from any supported online video — YouTube, TikTok, Facebook, X/Twitter, Vimeo, Dailymotion, Loom, Snapchat, and more — through a single endpoint.

This is now the single transcript endpoint for every supported platform, including YouTube. The endpoint auto-detects the platform from video_url and routes internally. (The old /youtube/transcript endpoint has been merged into /transcript.)

For Instagram videos, use the /transcribe endpoint instead (speech-to-text).

Billing

Billing depends on the URL:

  • YouTube (full transcript or metadata_only: true) → 1× residential_request (the fetch routes through the residential proxy).
  • Non-YouTube → 1× standard_request (some platforms internally require residential and are billed as residential_request accordingly).

The charge applies whether or not a transcript is returned, mirroring the proxy hop that was paid for. Set include_usage: true to receive a usage block in the response.

Overview

This endpoint automatically extracts rich video metadata and transcripts from online videos with high accuracy.

Supported Platforms

VidNavigator can retrieve transcripts from a wide variety of sources. Below is the list of platforms currently supported by this endpoint:

  • YouTube (uses residential proxy infrastructure for reliable access)
  • X / Twitter (just copy the tweet video link)
  • Facebook (public videos only)
  • TikTok
  • Dailymotion
  • Loom
  • Vimeo
  • Snapchat, when Snapchat provides a transcript: Show episodes often carry subtitles, most Spotlights do not. Use /transcribe for the others.

For Instagram videos, use the /transcribe endpoint instead, which runs speech-to-text.

Use Cases

Content Analysis

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

Search & Discovery

Enable text-based search across video content libraries

Accessibility

Generate captions and transcripts for accessibility compliance

Content Creation

Create summaries, articles, or repurpose video content

Request Parameters

ParameterTypeRequiredDescription
video_urlstringYesURL of the video to retrieve the transcript for (YouTube or any other supported platform)
languagestringNoISO2 language code (e.g., "en", "es", "fr")
metadata_onlybooleanNoWhen true, returns only video metadata without fetching the transcript. Takes precedence over fallback_to_metadata. Usage is still recorded.
fallback_to_metadatabooleanNoWhen true, returns video metadata with an empty transcript if transcript is unavailable (returns 200 instead of 404). Ignored if metadata_only is true.
transcript_textbooleanNoWhen true, returns the transcript as a single plain-text string instead of an array of segments.
include_usagebooleanNoWhen true, the response includes a usage block listing every meter charged during this request, the total credits deducted, and the remaining balance.

Example Usage

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

Transcript as Plain Text (transcript_text=true)

Use transcript_text=true to return the transcript as a single plain-text string instead of an array of { text, start, end } segments:

curl -X POST "https://api.vidnavigator.com/v1/transcript" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://twitter.com/user/status/123456789",
    "transcript_text": true
  }'

Getting Metadata Only

If you only need video metadata without the transcript (faster and still counts as usage):

curl -X POST "https://api.vidnavigator.com/v1/transcript" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://www.tiktok.com/@user/video/123456789",
    "metadata_only": true
  }'

For YouTube, metadata_only: true still routes through the residential proxy and is billed as a residential_request.

Getting Usage Disclosure (include_usage=true)

Set include_usage: true to receive a usage block describing exactly what was charged:

{
  "status": "success",
  "data": { "video_info": { ... }, "transcript": [ ... ] },
  "usage": {
    "charges": [
      { "service_type": "residential_request", "quantity": 1, "credits": 0.005 }
    ],
    "total_credits": 0.005
  }
}

Limitations

  • https://fb.watch/<video_id> format is not supported, use the https://www.facebook.com/watch/?v=<video_id> format instead.

Troubleshooting

  • Invalid URL: Ensure the video URL is complete and valid. This endpoint supports direct links from YouTube, X (a tweet), Vimeo, TikTok, etc.
  • 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. In which case, you will get a clear message stating that. Verify that the chosen language is available for the video. We recommend not using the language input if you are unsure.
  • For Instagram videos: This endpoint does not transcribe Instagram. Please use the /transcribe endpoint instead.

If issues persist or need more help, please reach out to us at support@vidnavigator.com.

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://example.com/thumbnail.jpg",
      "url": "https://twitter.com/user/status/123456789",
      "channel": "Example Creator",
      "duration": 45.5,
      "views": 123456,
      "likes": 9876,
      "published_date": "2024-01-15",
      "keywords": ["example", "twitter", "video"],
      "category": "Entertainment"
    },
    "transcript": [
      {
        "text": "This is the first sentence of the video.",
        "start": 0.5,
        "end": 3.2
      },
      {
        "text": "And this is the second sentence.",
        "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": "This is the first sentence of the video. And this is the second sentence."
  }
}

Response with metadata_only: true

When you set metadata_only: true, only the video metadata is returned:

{
  "status": "success",
  "data": {
    "video_info": {
      "title": "A Really Cool Video",
      "description": "An example description for the video.",
      "thumbnail": "https://example.com/thumbnail.jpg",
      "url": "https://twitter.com/user/status/123456789",
      "channel": "Example Creator",
      "duration": 45.5,
      "views": 123456,
      "likes": 9876,
      "published_date": "2024-01-15"
    }
  }
}

API reference

Authorization

ApiKeyAuth
headerX-API-Key<token>

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

Request Body

application/json
  1. body
video_url*string

URL of the video to retrieve transcript for

Formaturi
language?string

ISO2 language code (optional)

Length2 <= length <= 2
metadata_only?boolean

When true, returns only video metadata without transcript. Usage is still recorded.

Defaultfalse
fallback_to_metadata?boolean

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

Defaultfalse
transcript_text?boolean

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

Defaultfalse
include_usage?boolean

When true, the response includes the usage block of this request.

Defaultfalse

Response Body

Transcript retrieved successfully

application/json
  1. response
status?"success"
Value in"success"
data?
usage?

Per-call usage, returned only when the request sets include_usage=true: the charges of this request, one entry per service_type, and the total credits deducted. A waived charge carries waived: true and credits_saved, with a top-level waived.credits_saved summary.

For endpoints that run an AI analysis (/extract/video, /extract/file, /analyze/video, /analyze/file, /youtube/search), the analysis_request entry carries a nested tokens object with the request's token counts.

Example Request
curl -X POST 'https://api.vidnavigator.com/v1/transcript' \  -H 'Content-Type: application/json' \  -d '{  "video_url": "https://twitter.com/user/status/123456789"}'
Example Response
{  "status": "success",  "data": {    "video_info": {      "title": "string",      "description": "string",      "thumbnail": "http://example.com",      "url": "http://example.com",      "channel": "string",      "channel_url": "http://example.com",      "duration": 0,      "views": 0,      "likes": 0,      "published_date": "string",      "keywords": [        "string"      ],      "category": "string",      "available_languages": [        "string"      ],      "selected_language": "string",      "carousel_info": {        "total_items": 0,        "video_count": 0,        "image_count": 0,        "selected_index": 0      }    },    "transcript": [      {        "text": "string",        "start": 0,        "end": 0      }    ]  },  "usage": {    "charges": [      {        "service_type": "standard_request",        "quantity": 0,        "credits": 0,        "waived": true,        "credits_saved": 0,        "tokens": {          "prompt_tokens": 0,          "completion_tokens": 0,          "total_tokens": 0        }      }    ],    "total_credits": 0,    "waived": {      "credits_saved": 0    }  }}

On this page