跳转到主要内容
在 GitHub 上查看 → 无需单独配置 Google 的 YouTube 搜索。通过 AIsa 使用一个 API key 即可搜索视频、频道和播放列表。

安装

安装后启动新的智能体会话以加载该 Skill。

智能体可以用它做什么?

内容调研

围绕特定主题查找视频和频道。

趋势发现

发掘 YouTube 上正在受到关注的内容。

竞品追踪

监控细分领域的频道和内容形式。

主题探索

为研究工作流收集以视频为主的佐证资料。

快速开始

Base URL

所有 YouTube 搜索请求均通过该单一端点。AIsa 处理与底层 YouTube 数据源的身份验证 —— 你只需提供自己的 AIsa API key。

身份验证

所有请求都需要在 Authorization header 中包含 AIsa API key:
环境变量:将你的 API key 设置为 AISA_API_KEY:

获取你的 API Key

  1. 在 AIsa 控制台登录或创建账号
  2. 进入控制台
  3. 复制你的 API key

API 参考

YouTube 搜索

Query 参数

示例:基础搜索

示例:带国家和语言参数的搜索

示例:使用 sp Token 分页

响应

该 API 返回结构化的 YouTube 搜索结果,包括视频元数据、频道信息、缩略图和分页 token。 注意:响应结构可能会因查询语言而异。英文查询通常在 videos 数组中返回结果。某些非英文查询可能会将结果分组在 sections 数组中返回。请务必同时检查这两个字段。
备选响应结构(非英文 / 部分查询): 部分查询返回的结果会按 sections 分组,而不是扁平的 videos 数组:
同时解析两种格式:

高级搜索技巧

YouTube 的 q 参数支持与 YouTube 搜索框相同的搜索语法:

使用 sp 过滤 Token

sp 参数接收 YouTube 的编码过滤 token。常见取值: 你也可以从先前 API 响应中的 next_page_token 字段获取 sp token 来实现分页。

分页

使用响应中的 next_page_token 获取下一页结果:

代码示例

JavaScript

Python

Python(urllib,无依赖项)

注意:urllib 可能会因为其默认的 User-Agent 遇到 403 错误。建议使用 requests(见上文)。如果你必须使用 urllib,请务必设置自定义 User-Agent header。

与其他 AIsa API 结合使用

AIsa 的核心优势之一是统一的 API key。使用同一个 AISA_API_KEY,即可将 YouTube 搜索与 AIsa 的其他能力结合:

YouTube 搜索 + LLM 总结

YouTube 搜索 + Web 搜索

注意事项

  • 所有请求均通过你的 AIsa 余额按量计费 —— 无需单独管理 YouTube API 配额
  • engine 参数必须始终设置为 youtube
  • 视频 URL 遵循 https://www.youtube.com/watch?v={videoId} 格式
  • 频道 URL 遵循 https://www.youtube.com/channel/{channelId} 格式
  • 使用先前响应中的 next_page_token 作为分页的 sp 值
  • gl(国家/地区)参数不支持所有 ISO 国家代码。已知不支持的值包括 cn(中国)。如果你遇到 Unsupported value 错误,请尝试省略 gl 或使用其他国家代码
  • 非英文查询可能会在 sections 数组中返回结果,而不是扁平的 videos 数组 —— 请务必同时处理这两种格式
  • 重要提示:Python urllib 可能会因为其默认的 User-Agent 返回 403 错误。请改用 requests 库,或者添加自定义 User-Agent header
  • 重要提示:使用 curl 命令时,请确保 $AISA_API_KEY 等环境变量已正确展开
  • 重要提示:将 curl 输出通过管道传递给 jq 时,请使用 -s 参数并确保已设置 API key

错误处理

排错:API Key 问题

  1. 检查是否已设置 AISA_API_KEY 环境变量:
  1. 通过简单的测试验证 API key 是否正常工作:

排错:无搜索结果

  1. 确认你的查询词不为空
  2. 尝试使用更宽泛的搜索词
  3. 如果使用了 gl,请确认该国家代码受支持 —— 并非所有 ISO 代码均可用(例如不支持 cn)。可尝试省略 gl 来测试
  4. 确保每个请求中都包含 engine=youtube
  5. 检查结果是否位于 sections 而非 videos 中(在非英文查询中很常见)

资源

开始使用

  1. 在 aisa.one 注册并在控制台中创建 API key。
  2. 在你的终端中设置环境变量:export AISA_API_KEY="your-key"。
  3. 使用 安装 下的命令之一安装该 Skill,然后启动新的智能体会话。

相关

YouTube SERP

现有的面向 SERP 的 YouTube Skill。

AIsa YouTube 搜索

AIsa 原生的 YouTube 搜索工作流。

YouTube 搜索端点

YouTube 搜索的端点参考。