youtube-search

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 名称也可以。请勿省略此请求头，也不要发送默认的空值，否则 Cloudflare 将返回 403（错误代码 1010）并阻止请求。

API 参考

完整的 OpenAPI 规范：transcriptapi.com/openapi.json — 请参阅此文档以了解最新参数和架构。

GET /api/v2/youtube/search — 每页 1 个额度

在 YouTube 上全局搜索视频、频道、播放列表或电影。

GET https://transcriptapi.com/api/v2/youtube/search?q=QUERY&type=video&limit=20
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

参数	必填	默认值	验证
q	有条件	—	1-200 个字符（去除首尾空格），仅限第一页
type	否	video	video、channel、playlist、movie（仅限第一页）
sort	否	relevance	relevance 或 views（仅限第一页）
upload_date	否	—	hour、today、week、month、year — 视频，仅限第一页
duration	否	—	short（<4m）、medium（4-20m）、long（>20m）— 视频，仅限第一页
features	否	—	逗号分隔：hd、subtitles、cc、live、4k、hdr 等
limit	否	20	1-50
continuation	有条件	—	来自先前响应的令牌（后续页）

请准确提供 q（第一页）或 continuation（后续页）中的一个 — 令牌已包含筛选条件。sort/upload_date/duration/features 仅适用于第一页。

查找最新且观看次数最多的视频：

GET https://transcriptapi.com/api/v2/youtube/search?q=innovation&sort=views&duration=long&upload_date=month
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

搜索某个主题的播放列表：

GET https://transcriptapi.com/api/v2/youtube/search?q=react+tutorial&type=playlist
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

视频搜索响应：

{
  "results": [
    {
      "type": "video",
      "videoId": "dQw4w9WgXcQ",
      "title": "Rick Astley - Never Gonna Give You Up",
      "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
      "channelTitle": "Rick Astley",
      "channelHandle": "@RickAstley",
      "channelVerified": true,
      "lengthText": "3:33",
      "viewCountText": "1.5B views",
      "publishedTimeText": "14 years ago",
      "hasCaptions": true,
      "thumbnails": [{ "url": "...", "width": 120, "height": 90 }]
    }
  ],
  "result_count": 20
}

频道搜索响应（type=channel）：

{
  "results": [{
    "type": "channel",
    "channelId": "UCuAXFkgsw1L7xaCfnd5JJOw",
    "title": "Rick Astley",
    "handle": "@RickAstley",
    "url": "https://www.youtube.com/@RickAstley",
    "description": "Official channel...",
    "subscriberCount": "4.2M subscribers",
    "verified": true,
    "rssUrl": "https://www.youtube.com/feeds/videos.xml?channel_id=UC...",
    "thumbnails": [...]
  }],
  "result_count": 5
}

GET /api/v2/youtube/channel/search — 1 个额度

在指定频道内搜索视频。接受 channel 参数，可使用 @handle、频道 URL 或 UC... ID。

GET https://transcriptapi.com/api/v2/youtube/channel/search?channel=@TED&q=climate+change&limit=30
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

参数	必填	验证
channel	是	@handle、频道 URL 或 UC... ID
q	是	1-200 个字符
limit	否	1-50（默认值为 30）

最多返回约 30 个结果（YouTube 限制）。视频响应结构与全局搜索相同。

GET /api/v2/youtube/channel/resolve — 免费

将 @handle 转换为频道 ID：

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

工作流：搜索 → 文字记录

# 1. Search for videos
GET https://transcriptapi.com/api/v2/youtube/search?q=python+web+scraping&type=video&limit=5
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

# 2. Get transcript from result
GET https://transcriptapi.com/api/v2/youtube/transcript?video_url=VIDEO_ID&format=text&include_timestamp=true&send_metadata=true
Authorization: Bearer $TRANSCRIPT_API_KEY
User-Agent: YourAgent/1.0

错误

代码	含义	操作
401	API 密钥错误	检查密钥
402	额度不足	transcriptapi.com/billing
403/1010	被 Cloudflare 拦截	添加或修正 User-Agent 请求头
404	未找到	资源不存在
408	超时	重试一次
422	参数无效	检查参数格式

免费套餐：100 个额度，300 次请求/分钟。

复制粘贴示例

本文件中的每个请求都可以作为可直接运行的单行命令：references/curl-examples.md