YouTube 数据

通过 TranscriptAPI.com 访问 YouTube 数据 —— Google YouTube Data API 的轻量级替代方案。

环境配置

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

必需请求头

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

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

API 参考文档

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

视频数据（含字幕 + 元数据）—— 消耗 1 点积分

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

响应示例：

{
  "video_id": "dQw4w9WgXcQ",
  "language": "en",
  "transcript": [
    { "text": "We're no strangers to love", "start": 18.0, "duration": 3.5 }
  ],
  "metadata": {
    "title": "Rick Astley - Never Gonna Give You Up",
    "author_name": "Rick Astley",
    "author_url": "https://www.youtube.com/@RickAstley",
    "thumbnail_url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg"
  }
}

搜索数据 —— 消耗 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"

视频结果字段： videoId、title、channelId、channelTitle、channelHandle、channelVerified、lengthText、viewCountText、publishedTimeText、hasCaptions、thumbnails

频道结果字段（当 type=channel 时）： channelId、title、handle、url、description、subscriberCount、verified、rssUrl、thumbnails

频道数据

频道相关接口接受 channel 参数，其值可以是 @handle、频道 URL 或以 UC... 开头的频道 ID，无需预先解析。

将 handle 解析为频道 ID（免费）：

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": "UCsT0YIqwnpJCM-mx7-gSA4Q", "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"

返回内容包括：channel 信息，以及 results 数组，其中每项包含 videoId、title、published（ISO 格式时间戳）、viewCount（精确数值）、description 和 thumbnail 字段。

获取频道全部视频（分页，每页消耗 1 点积分）：

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

每页返回 100 条视频，并附带 continuation_token 用于分页。

在指定频道内执行搜索（消耗 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"

返回字段包括：results（视频列表）、playlist_info（含 title、numVideos、ownerName、viewCount）、continuation_token 和 has_more。

积分消耗明细

错误码说明

免费套餐：100 点积分，最高 300 次请求/分钟。