内容
# 🎬 YouTube 转录 API：纯净 JSON 的字幕和字幕
> 使用 YouTube 转录 API 的高效、可靠且开发者友好的方式。
**Actor 页面：** [apify.com/johnvc/YoutubeTranscripts](https://apify.com/johnvc/YoutubeTranscripts?fpr=9n7kx3)
**输入模式：** [apify.com/johnvc/YoutubeTranscripts/input-schema](https://apify.com/johnvc/YoutubeTranscripts/input-schema?fpr=9n7kx3)
YouTube 转录 API 提取一个或多个 YouTube 视频的转录，并返回纯净的结构化 JSON。每个视频都带有一个带有时间戳的字幕列表（文本、开始时间和持续时间）、纯文本版本的完整转录和语言元数据。它适用于标准视频、Shorts、youtu.be 短链接、嵌入 URL 和移动 URL，支持多 URL 并行处理，按视频计费。
## 视频演练
[](https://www.youtube.com/watch?v=jREWahDGhJM)
## 快速开始
### 先决条件
- Python 3.11 或更高版本
- Apify 账户和 API 密钥（[在此获取免费密钥](https://apify.com?fpr=9n7kx3)）
1. **克隆仓库**
```bash
git clone https://github.com/johnisanerd/Apify-Youtube-Transcripts-API.git
cd Apify-Youtube-Transcripts-API
```
2. **使用 UV 安装依赖项**
```bash
# 如果您没有安装 UV，请执行以下操作：
curl -LsSf https://astral.sh/uv/install.sh | sh
# 安装项目依赖项：
uv sync
```
3. **配置您的 API 密钥**
```bash
cp .env.example .env
# 编辑 .env 并添加您的 Apify API 密钥
# 在 https://apify.com?fpr=9n7kx3 获取您的免费 API 密钥
```
4. **运行示例**
```bash
uv run python youtube-transcripts-api.py
```
### 替代：直接设置 API 密钥
```bash
export APIFY_API_TOKEN="your_api_key_here"
uv run python youtube-transcripts-api.py
```
## 为什么使用此 YouTube 转录 API？
**两种转录格式。** 每个视频返回一个带有时间戳的字幕列表和纯文本版本，以便您可以构建交互式播放器或将纯文本直接馈入搜索和分析。
**多种 URL 格式。** 标准视频、Shorts、youtu.be 短链接、嵌入 URL 和移动 URL 都支持。
**批量并行处理。** 传递一个 URL 数组，每个 URL 并行处理；无效 URL 被记录为数据集中的错误，而不会停止运行。
**语言元数据。** 每个记录都报告转录语言、语言代码和字幕是否为自动生成的。
**可预测的、按需付费的定价。** 按视频计费，而不是按秒计费，无需订阅，这使得单个和批量运行都非常划算。
**易于自动化。** 从 Python 调用只需几行代码，或者将其加载为 MCP 工具，以便 Claude 和 Cursor 等助手可以为您按需提取转录。
## 功能
### 核心功能
- **单个或批量输入**：一个 URL 字符串或多个 URL 数组
- **广泛的 URL 支持**：标准视频、Shorts、youtu.be、嵌入和移动 URL
- **带有时间戳的字幕**，每个字幕段都有文本、开始时间和持续时间
- **纯文本转录**，作为单个字符串
- **每个视频的错误处理**：无效 URL 被记录，而不会导致运行失败
### 数据质量
- **每个视频的两种格式**：带有时间戳和纯文本
- **语言元数据**：语言名称、语言代码和自动生成标志
- **视频持续时间**（秒）
- **每个记录的成功标志**，便于轻松筛选
- **一致的 JSON 结构**，适用于每个视频
## 使用示例
### 单个视频
```json
{
"youtube_url": "https://www.youtube.com/watch?v=aircAruvnKk"
}
```
### 多个视频（批量）
```json
{
"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 并行处理。 |
## 输出格式
每个视频一个项目。下面的转录文本为占位符，以尊重内容版权；您自己的运行将返回实际的字幕文本。
```json
{
"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 转录 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 桌面版中安装
Cowork 是桌面应用程序的自动化模式。要为其提供 YouTube 转录 API 作为工具，请将 Apify MCP 服务器作为连接器添加。
1. 打开 Claude 桌面应用程序并转到 **设置 → 连接器** （或 **设置 → 开发者 → 编辑配置** 以直接编辑 `claude_desktop_config.json`）。
- macOS： `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows： `%APPDATA%\Claude\claude_desktop_config.json`
2. 添加 Apify MCP 服务器，仅预加载此 Actor：
```json
{
"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 转录 API。
下载桌面应用程序并开始免费试用： https://claude.ai/referral/uIlpa7nPLg
更多帮助： https://docs.apify.com/platform/integrations/claude-desktop
## 在 Claude Code 中安装
Claude Code 是命令行工具。通过一条命令添加 Actor 的 MCP 服务器：
```bash
claude mcp add --transport http apify \
"https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts"
```
使用令牌代替浏览器 OAuth：
```bash
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 转录 API。
免费试用 Claude Code： https://claude.ai/referral/uIlpa7nPLg
Claude Code MCP 文档： https://code.claude.com/docs/en/mcp
## 在 Claude（网站）中安装
在 claude.ai 上，您添加 Apify 作为连接器，然后启用此 Actor 的工具。
1. 进入 **设置 → 连接器 → 浏览连接器** 并搜索 **Apify MCP 服务器**。安装它（启用或更新，如果提示）。
2. 连接时，使用您的 Apify API 令牌进行身份验证，并启用 `johnvc/YoutubeTranscripts` 工具。
3. 在任何聊天中，打开 **+ → 连接器** 并启用 **Apify**。
4. 或者，选择 **添加自定义连接器** 并粘贴完整的 MCP URL `https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts`，在提示时使用 OAuth。
5. 请求 Claude 运行 YouTube 转录 API。
在网页上打开 Claude： https://claude.ai
## 在 Cursor 中安装
Cursor 从项目文件 `.cursor/mcp.json` 读取 MCP 服务器。
1. 在您的项目中创建 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"apify": {
"url": "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts"
}
}
}
```
2. 如果您更喜欢令牌身份验证而不是浏览器 OAuth，请添加一个标头：
```json
{
"mcpServers": {
"apify": {
"url": "https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts",
"headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" }
}
}
}
```
3. 打开 **Cursor → 设置 → MCP** 并确认 **apify** 服务器已连接（绿色点）。
4. 在 Composer 或 Chat 中，要求 Cursor 调用 YouTube 转录 API。
Cursor 新手？在此获取： https://cursor.com/referral?code=XQP4VBLI3NNX
## 在 ChatGPT 中安装
ChatGPT 通过开发者模式（适用于 ChatGPT Pro、Plus、Business、Enterprise 和 Education 计划）连接到 Apify MCP 服务器。
1. 点击您的个人资料图标，然后进入 **设置 > 应用**。如果您没有看到 **创建应用** 按钮，请打开 **高级设置** 并启用 **开发者模式**。
2. 点击 **创建应用** 并填写表格：
- **名称：** Apify
- **MCP 服务器 URL：** `https://mcp.apify.com/?tools=actors,docs,johnvc/YoutubeTranscripts`
- **身份验证：** OAuth
3. 点击 **创建** 并使用 Apify 授权连接。
4. 要在对话中使用应用，请点击聊天中的 **+**，选择 **开发者模式**，然后选择 **Apify**。
更多帮助： https://docs.apify.com/platform/integrations/mcp
---
[**精心制作**](https://apify.com/johnvc?fpr=9n7kx3)
*使用 YouTube 转录 API 为内容再利用、搜索索引和研究提供可靠的结构化字幕。*
最后更新： 2026.06.30
