youtube-api

YouTube API

按需获取 YouTube 数据：支持按真实筛选条件搜索视频、频道和播放列表 （上传日期、时长、排序方式），查询频道和视频，获取视频、 Shorts、直播、播放列表内容、评论、话题标签动态和热门内容 ——每次调用只需发送一个普通 HTTP GET，按需付费。无需开发者控制台项目、 OAuth 同意屏幕或每日配额。

基础 URL：https://youtube.fetcher.sh

身份验证

两种付费方式，数据相同 — 完整机制见 fetcher 技能：

# 1. Prepaid credits (recommended — get a key at https://fetcher.sh/topup
#    or via POST /api/credits/topup, see the fetcher skill)
export FETCHER_API_KEY="bby_live_xxxxxxxxxxxx"
curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/search/video?query=hello"

# 2. x402 pay-per-call — omit the header; a GET with no payment returns 402
#    with machine-readable payment requirements (USDC on Base, Polygon,
#    Arbitrum, Monad, or Solana). @x402/fetch signs and retries automatically.

每个响应的格式都是 { "status": number, "message": string, "data": ... }；HTTP 状态码与 status 一致。

端点（15 个 — 全部为 GET，每次调用 $0.005）

端点	返回内容
/api/search/video	符合搜索条件的视频；可按上传日期、时长和排序方式筛选
/api/search/channel	符合搜索条件的频道
/api/search/playlist	符合搜索条件的播放列表
/api/channel/{id}	按 ID 获取频道详情
/api/channel/handle/{handle}	按 @handle 获取频道详情
/api/channel/path	按自定义 URL 路径获取频道详情
/api/channel/{id}/videos	频道的视频
/api/channel/{id}/shorts	频道的 Shorts
/api/channel/{id}/live-streams	频道的直播
/api/video/{id}	视频（或 Short）详情
/api/video/{id}/comments	视频评论
/api/shorts/{id}	Short 详情
/api/playlist/{id}/videos	播放列表中的视频
/api/hashtag/{tag}	某个话题标签下的视频
/api/trending	热门视频，可按地区筛选

{id} / {handle} / {tag} 是路径参数。可选的 cursor / lang / geo 用于细化结果；query（搜索）和 channelPath（路径 查询）在出现时为必填项。

场景

本周上传：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=ai agents" -G \
  --data-urlencode "uploadDate=week" \
  "https://youtube.fetcher.sh/api/search/video"

仅查看播放量最高的长视频：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=x402 protocol" -G \
  --data-urlencode "sortBy=view_count" \
  --data-urlencode "duration=long" \
  "https://youtube.fetcher.sh/api/search/video"

按最新优先排序：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=stablecoin payments" -G \
  --data-urlencode "sortBy=upload_date" \
  "https://youtube.fetcher.sh/api/search/video"

其他 uploadDate 值：hour、today、month、year。其他 duration 值：short、medium。其他 sortBy 值：relevance、rating。

搜索频道或播放列表：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=lofi hip hop" -G \
  "https://youtube.fetcher.sh/api/search/channel"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "query=lofi hip hop" -G \
  "https://youtube.fetcher.sh/api/search/playlist"

通过 ID、handle 或自定义路径查询频道 — 然后获取其视频、Shorts 和直播：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/channel/handle/mkbhd"

curl -H "Authorization: Bearer $FETCHER_API_KEY" -G \
  --data-urlencode "channelPath=@mkbhd" \
  "https://youtube.fetcher.sh/api/channel/path"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/channel/UCBJycsmduvYEL83R_U4JriQ/videos"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/channel/UCBJycsmduvYEL83R_U4JriQ/shorts"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/channel/UCBJycsmduvYEL83R_U4JriQ/live-streams"

查询视频详情和评论，或 Short 的详情：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/video/dQw4w9WgXcQ"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "sort=top" -G \
  "https://youtube.fetcher.sh/api/video/dQw4w9WgXcQ/comments"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/shorts/abc123XYZ90"

获取播放列表中的视频、话题标签下的视频，以及热门内容（按地区）：

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/playlist/PLFgquLnL59alCl_2TQvOiD5Vgm1hCaGSI/videos"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  "https://youtube.fetcher.sh/api/hashtag/shorts"

curl -H "Authorization: Bearer $FETCHER_API_KEY" \
  --data-urlencode "geo=US" -G \
  "https://youtube.fetcher.sh/api/trending"

MCP

{
  "mcpServers": {
    "youtube": {
      "url": "https://youtube.fetcher.sh/mcp",
      "headers": { "Authorization": "Bearer bby_live_..." }
    }
  }
}

免费工具：search_endpoints、describe_endpoint、check_balance。付费工具： fetch_data（上方任意端点）、topup_credits，以及名为 youtube_search_video 的快捷工具。若要改用 x402 按次付费，请移除 headers 代码块 — 完整流程请参阅 fetcher 技能。

错误

• 400 — 参数缺失或无效（消息会指出参数）
• 401 — 密钥未知或已轮换
• 402 — 需要付款（x402 挑战）或 topup_required（额度已用尽）
• 404 — 非计价路径
• 无速率限制；上游失败不退款（结算先于交付）

参考

• 完整的 Agent 设置说明：https://youtube.fetcher.sh/skill.md
• OpenAPI 3.1 合约：https://youtube.fetcher.sh/openapi.json
• 精简目录：https://youtube.fetcher.sh/llms.txt
• 付款、额度和 MCP 深入说明：fetcher 技能
• 网站：https://youtube.fetcher.sh