TranscriptYT

YouTube转录供AI代理使用：支持150多种语言的文本、JSON、SRT或VTT格式，并提供翻译和AI转录回退功能。

托管 MCP 服务器

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

可安装到 Claude Code、Codex、Cursor 等客户端

文档

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.