youtube-transcripts

🎬 YouTube Transcripts API：以简洁的 JSON 获取字幕和字幕文本

高效、可靠且对开发者友好的 YouTube Transcripts API 使用方式。

Actor 页面： apify.com/johnvc/YoutubeTranscripts 输入架构： apify.com/johnvc/YoutubeTranscripts/input-schema

YouTube Transcripts API 可提取一个或多个 YouTube 视频的字幕文本，并返回简洁、结构化的 JSON。每个视频都会返回带时间戳的字幕列表（文本、起始时间和时长）、完整字幕的纯文本版本，以及语言元数据。它支持普通视频、Shorts、youtu.be 短链接、嵌入式 URL 和移动端 URL，可并行处理多个 URL，并按视频计费。

视频演示

快速开始

前提条件

• Python 3.11 或更高版本
• Apify 账号和 API 密钥（在此免费获取密钥）

1. 克隆代码库

   git clone https://github.com/johnisanerd/Apify-Youtube-Transcripts-API.git
   cd Apify-Youtube-Transcripts-API
   

2. 使用 UV 安装依赖项

   # Install UV if you do not have it:
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install project dependencies:
   uv sync
   

3. 配置 API 密钥

   cp .env.example .env
   # Edit .env and add your Apify API key
   # Get your free API key at: https://apify.com?fpr=9n7kx3
   

4. 运行示例

   uv run python youtube-transcripts-api.py
   

备选方案：直接设置 API 密钥

export APIFY_API_TOKEN="your_api_key_here"
uv run python youtube-transcripts-api.py

为什么使用这个 YouTube Transcripts API？

两种字幕格式。 每个视频都会返回带时间戳的字幕列表和纯文本版本，让你可以构建交互式播放器，或将简洁文本直接用于搜索和分析。

支持多种 URL 格式。 普通视频、Shorts、youtu.be 短链接、嵌入式 URL 和移动端 URL 均可使用。

并行批量处理。 传入 URL 数组即可并行处理每个 URL；无效 URL 会作为错误记录在数据集中，不会中断运行。

语言元数据。 每条记录都会报告字幕语言、语言代码，以及字幕是否为自动生成。

价格可预测，按使用量付费。 按视频计费，而非按秒计费，且无需订阅，因此单个视频和批量处理的成本都很低。

易于自动化。 只需几行 Python 代码即可调用，也可以将其加载为 MCP 工具，让 Claude 和 Cursor 等助手按需获取字幕文本。

功能

核心能力

• 单条或批量输入：传入一个字符串形式的 URL，或一个包含多个 URL 的数组
• 广泛支持 URL：普通视频、Shorts、youtu.be、嵌入式和移动端 URL
• 带时间戳的字幕：每个片段都包含文本、起始时间和时长
• 纯文本字幕：以单个字符串形式返回
• 逐视频错误处理：记录无效 URL，但不会导致运行失败

数据质量

• 每个视频提供两种格式：带时间戳和纯文本
• 语言元数据：语言名称、语言代码和自动生成标记
• 视频时长：以秒为单位
• 每条记录均包含成功标记，便于筛选
• 所有视频的 JSON 结构保持一致

使用示例

单个视频

{
  "youtube_url": "https://www.youtube.com/watch?v=aircAruvnKk"
}

多个视频（批量处理）

{
  "youtube_url": [
    "https://www.youtube.com/watch?v=aircAruvnKk",
    "https://youtu.be/9bZkp7q19f0",
    "https://www.youtube.com/shorts/abcdEFGhijk"
  ]
}

输入参数

参数	类型	必填	默认值	说明
youtube_url	string 或 array	是	-	一个字符串形式的 YouTube URL，或多个 URL 组成的数组。支持普通视频、Shorts、youtu.be、嵌入式和移动端 URL。每个 URL 都会并行处理。

输出格式

每个视频对应一条记录。以下字幕文本仅为占位内容，用于尊重内容版权；你运行后会获得实际字幕文本。

{
  "video_id": "aircAruvnKk",
  "language": "English",
  "language_code": "en",
  "is_generated": false,
  "total_seconds": 1105.64,
  "timestamped": [
    { "text": "<caption segment text>", "start": 4.22, "duration": 1.18 }
  ],
  "non_timestamped": "<full transcript as a single plain-text string>",
  "url": "https://www.youtube.com/watch?v=aircAruvnKk",
  "timestamp": "2026-05-29T11:58:40",
  "success": true
}

timestamped 数组包含每个字幕片段的一条记录，其中包含以秒为单位的 text、start 和 duration；non_timestamped 是以单个字符串形式返回的完整字幕文本。语言元数据（language、language_code、is_generated）和 total_seconds 描述视频信息；找到字幕时，success 为 true。无效或不可用的 URL 会以 success: false 返回，并附带错误说明。

---

用作 MCP 工具

你可以将 YouTube Transcripts API 加载为 MCP 工具，让助手代你调用。MCP 服务 URL 仅预加载此 Actor：

https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts

如果出现 OAuth 提示，请在浏览器中完成身份验证；也可以使用 Apify API 令牌（与 Python 示例中使用的 APIFY_API_TOKEN 相同）。请访问 https://console.apify.com/settings/integrations 获取令牌，并访问 https://apify.com?fpr=9n7kx3 创建免费的 Apify 账户。

在 Claude Cowork Desktop 中安装

Cowork 是桌面应用的自动化模式。若要将 YouTube Transcripts API 添加为工具，请添加 Apify MCP 服务作为连接器。

1. 打开 Claude 桌面应用，前往 Settings → Connectors（或前往 Settings → Developer → Edit Config，直接编辑 claude_desktop_config.json）。
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
2. 添加仅预加载此 Actor 的 Apify MCP 服务：

{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts"
      ]
    }
  }
}

3. 重启应用。Cowork 首次调用该工具时，请在浏览器中完成 OAuth 提示；或者在连接器设置中添加 Apify API 令牌，以跳过 OAuth。
4. 在 Cowork 聊天中，确认工具可用，并让它运行 YouTube Transcripts API。

下载桌面应用并开始免费试用：https://claude.ai/referral/uIlpa7nPLg 更多帮助：https://docs.apify.com/platform/integrations/claude-desktop

在 Claude Code 中安装

Claude Code 是命令行工具。使用一条命令添加 Actor 的 MCP 服务：

claude mcp add --transport http apify \
  "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts"

若要使用令牌而不是浏览器 OAuth：

claude mcp add --transport http apify \
  "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts" \
  --header "Authorization: Bearer YOUR_APIFY_TOKEN"

然后使用 claude mcp list 验证，或在会话中运行 /mcp。让 Claude Code 调用 YouTube Transcripts API。

免费试用 Claude Code：https://claude.ai/referral/uIlpa7nPLg Claude Code MCP 文档：https://code.claude.com/docs/en/mcp

在 Claude（网站）中安装

在 claude.ai 上，你需要将 Apify 添加为连接器，然后启用此 Actor 的工具。

1. 前往 Settings → Connectors → Browse connectors，搜索 Apify MCP server。安装它（如果出现提示，请启用或更新）。
2. 连接时，使用 Apify API 令牌进行身份验证，并启用工具 johnvc/YoutubeTranscripts。
3. 在任意聊天中，打开 + → Connectors 并启用 Apify。
4. 也可以选择 Add custom connector，粘贴完整的 MCP URL https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts，并在出现提示时使用 OAuth。
5. 让 Claude 运行 YouTube Transcripts API。

在网页上打开 Claude：https://claude.ai/referral/uIlpa7nPLg

在 Cursor 中安装

Cursor 从项目文件 .cursor/mcp.json 中读取 MCP 服务。

1. 在项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts"
    }
  }
}

2. 如果你更倾向于使用令牌身份验证而不是浏览器 OAuth，请添加一个标头：

{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts",
      "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
    }
  }
}

3. 打开 Cursor → Settings → MCP，确认 apify 服务已连接（显示绿点）。
4. 在 Composer 或 Chat 中，让 Cursor 调用 YouTube Transcripts API。

刚开始使用 Cursor？在此获取：https://cursor.com/referral?code=XQP4VBLI3NNX

在 ChatGPT 中安装

ChatGPT 通过开发者模式连接到 Apify MCP 服务（适用于 ChatGPT Pro、Plus、Business、Enterprise 和 Education 计划）。

1. 点击个人资料图标，然后前往 Settings > Apps。如果看不到 Create app 按钮，请打开 Advanced settings 并启用 Developer mode。
2. 点击 Create app 并填写表单：
   • Name： Apify
   • MCP Server URL： https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts
   • Authentication： OAuth
3. 点击 Create，并通过 Apify 授权连接。
4. 要在对话中使用此应用，请点击聊天中的 +，选择 Developer mode，然后选择 Apify。

更多帮助：https://docs.apify.com/platform/integrations/mcp

---

用心打造

使用 YouTube Transcripts API，通过可靠、结构化的字幕支持内容再利用、搜索索引和研究。

🤖 向 AI 助手询问此 Actor

在你选择的 AI 中打开一条可直接发送的提示词，了解 YouTube Transcripts API：

• 💬 ChatGPT
• 🧠 Claude
• 🔍 Perplexity
• 🅒 Copilot

最后更新：2026.10.27