TranscriptYT

npx add-mcp 'https://transcript-yt.com/mcp'

Reference

YouTube Transcript API Reference

The base URL for every endpoint below is https://transcript-yt.com. Grab a key from your dashboard first. A machine-readable OpenAPI 3.1 spec is available for code generation and agent tooling.

Quickstart

Create a key, then request a transcript by URL or video ID:

curl "https://transcript-yt.com/v1/transcript?url=5f3Pn-N6yLc" \
  -H "Authorization: Bearer ts_live_xxxx"

AI agents (MCP)

Connect TranscriptYT to Claude Code, Codex, Cursor, VS Code, or Claude Desktop through our MCP server at https://transcript-yt.com/mcp. Replace ts_live_... with your key.

claude mcp add --transport http transcriptyt https://transcript-yt.com/mcp \
  --header "Authorization: Bearer ts_live_..."

Your agent gets six tools:

• get_transcript: transcript by URL or ID, with optional language, translate_to, format (defaults to md), and timestamps. 1 credit.
• summarize_video: summary, key points, and timestamped notes from a video's transcript. 2 credits for most videos, more for long ones.
• list_languages: available caption tracks. Free.
• list_playlist_videos: videos in a playlist or a channel's uploads. Free.
• search_youtube: search YouTube, or within one channel. Free.
• get_usage: remaining credits. Free.

Authentication

Pass your key as a bearer token. x-api-key also works if a header library makes that easier.

Authorization: Bearer ts_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

GET /v1/transcript

Fetch a transcript for any public YouTube video.

Param	Type	Description
url	string, required	A YouTube URL (watch, youtu.be, shorts, embed) or a bare 11-char video ID.
language	string, optional	BCP-47 code (e.g. es, pt-BR). Defaults to the original / English track. If the video has no track in that language, the original is machine-translated into it and translated is true.
translate_to	string, optional	BCP-47 target code, any of 150+ languages. Machine-translates whichever track language selects, keeping every segment's timing. The response's language becomes the target and translated is true.
format	string, optional	json (default), text, srt, vtt,csv, or md.
includeSegments	boolean, optional	Set false to drop the timestamped array and return only full text (JSON format only).
timestamps	boolean, optional	Set true to prefix each line with a [HH:MM:SS] marker in text and md output. Formatting is free, with no extra credit cost.
paragraphs	boolean, optional	Set true to merge segments into paragraph-length chunks (on speech pauses or a character budget) instead of raw caption cues.
chunkSize	integer, optional	With paragraphs=true, the maximum characters per paragraph (50 to 10000, default 400).
captionType	string, optional	any (default), manual for uploaded captions only, or auto for YouTube's auto-generated captions only.
originalLanguage	boolean, optional	Set true to get captions in the language actually spoken instead of the English track. Ignored when language is set.
mode	string, optional	auto (default) uses captions and falls back to AI transcription. captions never uses AI. ai transcribes the audio even when captions exist (billed per minute).
startTime / endTime	number, optional	Seconds. Return only the part of the transcript in this range.
search	string, optional	Return only the lines containing this text (case-insensitive), each with its timestamp.

Also available as POST /v1/transcript with a JSON body of the same shape.

curl "https://transcript-yt.com/v1/transcript?url=https://youtu.be/5f3Pn-N6yLc" \
  -H "Authorization: Bearer ts_live_xxxx"

{
  "videoId": "5f3Pn-N6yLc",
  "title": "How To Clean Up Gmail Inbox - Fast and Easily",
  "author": "Tech is Easy",
  "channelId": "UCu7hJvEMoy36jfbJXp6heRg",
  "durationSeconds": 151,
  "language": "en",
  "translated": false,
  "autoGenerated": true,
  "source": "captions",
  "segments": [
    { "start": 0.24, "duration": 3.84, "end": 4.08, "timestamp": "0:00", "text": "in the next two to three minutes I'm" },
    { "start": 2.159, "duration": 3.481, "end": 5.64, "timestamp": "0:02", "text": "gonna show you how to clean up your" }
  ],
  "text": "in the next two to three minutes I'm gonna show you how to clean up your ...",
  "availableLanguages": [
    { "languageCode": "en", "languageName": "English (auto-generated)", "autoGenerated": true }
  ]
}

POST /v1/transcripts

Up to 50 videos in one call. Send urls plus any of the options above; each video is billed and rate-limited like a single request, and one failure doesn't fail the batch. Videos beyond your per-minute rate limit come back as RATE_LIMITED items to retry.

curl -X POST "https://transcript-yt.com/v1/transcripts" \
  -H "Authorization: Bearer ts_live_xxxx" -H "Content-Type: application/json" \
  -d '{"urls": ["5f3Pn-N6yLc", "https://youtu.be/dQw4w9WgXcQ"], "format": "text"}'

{
  "total": 2, "succeeded": 2, "failed": 0,
  "results": [
    { "url": "5f3Pn-N6yLc", "ok": true, "cached": true, "body": "in the next two to three minutes..." },
    ...
  ]
}

JSON-format items carry a transcript object; other formats carry the file as body.

A whole playlist or channel. Send playlist (a playlist link or ID, or a channel link or @handle) instead of urls, with an optional limit (up to 50). Channels return their newest uploads first.

curl -X POST "https://transcript-yt.com/v1/transcripts" \
  -H "Authorization: Bearer ts_live_xxxx" -H "Content-Type: application/json" \
  -d '{"playlist": "https://www.youtube.com/@mkbhd", "limit": 10, "format": "md"}'

GET /v1/playlist

List the videos in a playlist, or a channel's uploads, without fetching any transcripts. Free. limit defaults to 100 (max 500).

curl "https://transcript-yt.com/v1/playlist?url=@mkbhd&limit=3" \
  -H "Authorization: Bearer ts_live_xxxx"

{
  "kind": "channel",
  "id": "UUBJycsmduvYEL83R_U4JriQ",
  "title": "Marques Brownlee",
  "videos": [
    { "videoId": "...", "title": "...", "durationSeconds": 742 },
    ...
  ],
  "truncated": true
}

GET /v1/search

Search YouTube for videos, or pass channel (a channel link or @handle) to search within one channel. Free. limit defaults to 20 (max 100).

curl "https://transcript-yt.com/v1/search?q=iphone&channel=@mkbhd&limit=2" \
  -H "Authorization: Bearer ts_live_xxxx"

{
  "query": "iphone",
  "channelId": "UCBJycsmduvYEL83R_U4JriQ",
  "videos": [
    {
      "videoId": "...",
      "title": "...",
      "channelTitle": "Marques Brownlee",
      "channelId": "UCBJycsmduvYEL83R_U4JriQ",
      "durationSeconds": 1034,
      "viewCount": 27507991,
      "published": "3 weeks ago"
    },
    ...
  ],
  "truncated": true
}

GET /v1/summary

Summary, key points, and timestamped study notes for a video, generated from its transcript. Written in the transcript's language; translate_to summarizes a translated transcript instead. Costs 1 credit for the transcript plus the summary's AI cost: 1 credit for videos up to about 25 minutes and for already-cached summaries, about 1 more per further 45 minutes of speech. Most requests cost 2 credits; X-Credits-Charged shows the total.

curl "https://transcript-yt.com/v1/summary?url=5f3Pn-N6yLc" \
  -H "Authorization: Bearer ts_live_xxxx"

{
  "videoId": "5f3Pn-N6yLc",
  "title": "...",
  "author": "...",
  "language": "en",
  "cached": { "transcript": true, "summary": false },
  "summary": "...",
  "keyPoints": ["...", "..."],
  "notes": [
    { "start": 42, "heading": "...", "bullets": ["...", "..."] },
    ...
  ]
}

GET /v1/languages

List available caption tracks for a video without downloading one, plus every language translateTo accepts. This call does not cost a credit.

curl "https://transcript-yt.com/v1/languages?url=5f3Pn-N6yLc" \
  -H "Authorization: Bearer ts_live_xxxx"

{
  "videoId": "5f3Pn-N6yLc",
  "languages": [
    { "languageCode": "en", "languageName": "English (auto-generated)", "autoGenerated": true }
  ],
  "translationLanguages": [
    { "languageCode": "af", "languageName": "Afrikaans" },
    ...
  ]
}

Output formats

format=srt, format=vtt, format=csv, and format=md return files directly with a matching Content-Type. Pipe the response straight to a file. Every format is generated from the same underlying transcript at no extra credit cost, including timestamps and paragraphs.

Videos with no captions. When a video has no caption track, we transcribe its audio with AI speech-to-text (videos up to about two hours). The response has source: "speech_to_text" and autoGenerated: true, and costs 1 credit per started minute of audio (see the X-Credits-Charged header). Repeat requests for the same video are cache hits and cost 1 credit. language and translate_to work the same way on these transcripts.

curl "https://transcript-yt.com/v1/transcript?url=5f3Pn-N6yLc&format=srt" \
  -H "Authorization: Bearer ts_live_xxxx" -o captions.srt

GET /v1/usage

Current plan, credit balance (plan + top-up), and rate limit. Free, never costs a credit.

curl "https://transcript-yt.com/v1/usage" \
  -H "Authorization: Bearer ts_live_xxxx"

{
  "plan": "STARTER",
  "credits_remaining": 3820,
  "plan_credits": { "total": 4000, "used": 180, "remaining": 3820 },
  "topup_credits": { "remaining": 0, "grants": [] },
  "period_resets_at": "2026-10-19T00:00:00.000Z",
  "rate_limit_per_minute": 60
}

Errors

Every error uses the same envelope, except 402 (see below):

{ "error": { "code": "NO_CAPTIONS", "message": "This video has no captions available." } }

Code	HTTP	Meaning
INVALID_VIDEO	400	Couldn't parse a video ID from the given url
VIDEO_UNAVAILABLE	404	Video is private, deleted, or region-locked
NO_CAPTIONS	404	Video has no captions and its audio could not be AI-transcribed
LANGUAGE_NOT_AVAILABLE	404	Requested language isn't offered
UNAUTHORIZED	401	Missing or invalid API key
RATE_LIMITED	429	Too many requests per minute
BLOCKED	503	Temporary upstream block. Retry shortly.

Out of credits is a 402 with its own flat shape rather than the error envelope above:

{
  "error": "Out of credits",
  "plan": "MICRO",
  "credits_remaining": 0,
  "upgrade_url": "https://transcript-yt.com/dashboard/billing",
  "topup_url": "https://transcript-yt.com/dashboard/billing#topup"
}

Failed requests (any 4xx/5xx from us) are never billed a credit.

Rate limits & credits

Every response carries usage headers so you can back off before hitting a wall. A 429 also carries Retry-After (seconds):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1737403200
Retry-After: 12
X-Credits-Charged: 1
X-Credits-Remaining: 3786

X-Credits-Charged is the credits billed for that call (including cache hits) and 0 on any failure. X-Credits-Remaining is your plan balance plus any active top-up packs. See the pricing page for per-plan limits.