subtitles

用途

该工具用于获取 YouTube 视频的字幕或口语文本。当需要某段 YouTube 视频的字幕时使用，适用于用户粘贴的视频链接或视频 ID、视频翻译请求、跟读、按字幕阅读等场景。

主要能力

通过 TranscriptAPI.com 接口获取 YouTube 视频字幕。支持指定视频并选择返回格式：

format=json：返回带时间信息的分段字幕，适合需要与时间轴同步的阅读场景。
format=text：返回纯文本，可配合 include_timestamp=false 使用，得到适合阅读、翻译、语言学习的干净文本。
send_metadata=true：可在响应中包含视频标题、频道、描述等元数据。

使用方式

初始化

若未设置 $TRANSCRIPT_API_KEY，需阅读 references/auth-setup.md 并按其中说明获取并保存密钥。

必填请求头

每个请求都必须包含两个请求头：

Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent：填代理的名称与版本（若已知），例如 HermesAgent/0.11.0、ClaudeCode/1.0；版本可省略，仅代理名称亦可。不可省略该请求头，也不要发送空的默认值，否则 Cloudflare 会返回 403（错误码 1010）并拦截请求。

接口

GET https://transcriptapi.com/api/v2/youtube/transcript

参数说明：

video_url：YouTube URL 或视频 ID（必填）。
format：可选 json、text。需要带时间轴的字幕时用 json。
include_timestamp：可选 true、false。设为 false 可得到适合阅读/翻译的干净文本。
send_metadata：可选 true、false。设为 true 时包含标题、频道、描述。

语言学习场景（不含时间戳的干净文本）：

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=false
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

翻译场景（结构化分段）：

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=json&include_timestamp=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

完整请求示例：

GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_URL&format=text&include_timestamp=false&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

响应示例

format=json：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 18.0, "duration": 3.5 }
  ]
}

format=text 且 include_timestamp=false：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": "We're no strangers to love\nYou know the rules and so do I..."
}

使用建议

许多视频带有多种语言的自动生成字幕。
使用 format=json 可获得每行字幕的时间信息，适合同步阅读。
使用 include_timestamp=false 可获得适合翻译应用的干净文本。
文件中每个请求的可直接运行的一行命令示例见 references/curl-examples.md。

错误处理

401：API 密钥错误，请检查密钥。
402：无可用额度，参见 transcriptapi.com/billing。
403/1010：Cloudflare 拦截，添加或修正 User-Agent 请求头。
404：无字幕，该视频没有可用字幕。
408：超时，等待 2 秒后重试一次。

限制与计费

每次请求消耗 1 credit。免费额度为 100 credits，每分钟 300 请求。