YouTube 全功能

通过 TranscriptAPI.com 提供的完整 YouTube 工具套件。所有功能集成于一项能力中。

配置

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

必需请求头

每个请求均需包含以下两个请求头：

• Authorization（授权）： Bearer $TRANSCRIPT_API_KEY
• User-Agent（用户代理）： 请填写您的 agent 名称及版本号（如 HermesAgent/0.11.0、ClaudeCode/1.0）。版本号为可选字段，仅提供 agent 名称亦可；但不可省略此请求头，也不可发送空值或默认值（例如 curl/7.68.0 等），否则 Cloudflare 将返回 HTTP 403 错误（错误码 1010）并拒绝请求。

API 参考文档

完整 OpenAPI 规范地址：transcriptapi.com/openapi.json —— 请以此为准查阅最新参数定义与数据结构。

视频字幕提取（1 信用点）

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

响应示例（format=json）：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [{ "text": "...", "start": 18.0, "duration": 3.5 }],
  "metadata": { "title": "...", "author_name": "...", "author_url": "..." }
}

搜索（1 信用点）

# 搜索视频
curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

# 搜索频道
curl -s "https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=channel&limit=10" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

频道相关接口

所有频道端点均支持传入 channel 参数，其值可以是 @handle（如 @TED）、频道 URL 或以 UC... 开头的频道 ID，无需预先解析。

解析 handle（免费）

curl -s "https://transcriptapi.com/api/v2/youtube/channel/resolve?input=@TED" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

响应示例：{"channel_id": "UC...", "resolved_from": "@TED"}

获取最新 15 条视频（免费）

curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

返回精确的 viewCount（观看次数）和符合 ISO 标准的 published（发布时间戳）。

获取频道全部视频（每页 1 信用点）

# 第一页（最多 100 条视频）
curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?channel=@NASA" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

# 后续分页
curl -s "https://transcriptapi.com/api/v2/youtube/channel/videos?continuation=TOKEN" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

必须且仅能提供 channel 或 continuation 其中之一。响应体中将包含 continuation_token 和 has_more 字段。

在指定频道内搜索（1 信用点）

curl -s "https://transcriptapi.com/api/v2/youtube/channel/search
?channel=@TED&q=QUERY&limit=30" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

播放列表（每页 1 信用点）

支持传入 playlist 参数，其值可以是 YouTube 播放列表 URL 或播放列表 ID。

# 第一页
curl -s "https://transcriptapi.com/api/v2/youtube/playlist/videos?playlist=PL_ID" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

# 后续分页
curl -s "https://transcriptapi.com/api/v2/youtube/playlist/videos?continuation=TOKEN" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

合法的播放列表 ID 前缀包括：PL、UU、LL、FL、OL。响应体中包含 playlist_info、results、continuation_token 和 has_more 字段。

信用点消耗明细

参数校验规则

错误码说明

典型使用流程

研究型工作流： 搜索 → 选取视频 → 获取字幕

# 1. 搜索
curl -s "https://transcriptapi.com/api/v2/youtube/search
?q=machine+learning+explained&limit=5" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"
# 2. 获取字幕
curl -s "https://transcriptapi.com/api/v2/youtube/transcript
?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

频道监控工作流： 获取最新视频（免费）→ 获取字幕

# 1. 获取最新上传视频（免费 — 直接传入 @handle）
curl -s "https://transcriptapi.com/api/v2/youtube/channel/latest?channel=@TED" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"
# 2. 获取最新视频的字幕
curl -s "https://transcriptapi.com/api/v2/youtube/transcript
?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true" 
  -H "Authorization: Bearer $TRANSCRIPT_API_KEY" 
  -H "User-Agent: YourAgent/1.0"

免费套餐：100 信用点，300 次请求/分钟；入门版（$5/月）：1,000 信用点。