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 three tools:

• get_transcript — transcript by URL or ID, with optional language, translate_to, format (defaults to md), and timestamps. 1 credit.
• list_languages — available caption tracks. 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 — 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.

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, "text": "in the next two to three minutes I'm" },
    { "start": 2.159, "duration": 3.481, "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 }
  ]
}

GET /v1/languages

List available caption tracks for a video without downloading one. 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 }
  ]
}

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 an hour). The response has source: "speech_to_text" and autoGenerated: true, and costs 1 credit per started 3 minutes of audio (see the X-Credits-Charged header). 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 1 on a billed response (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.