安装
智能体可以用它做什么?
内容调研
围绕特定主题查找视频和频道。
趋势发现
发掘 YouTube 上正在受到关注的内容。
竞品追踪
监控细分领域的频道和内容形式。
主题探索
为研究工作流收集以视频为主的佐证资料。
快速开始
Base URL
身份验证
所有请求都需要在 Authorization header 中包含 AIsa API key:AISA_API_KEY:
获取你的 API Key
- 在 AIsa 控制台登录或创建账号
- 进入控制台
- 复制你的 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-Agentheader - 重要提示:使用 curl 命令时,请确保
$AISA_API_KEY等环境变量已正确展开 - 重要提示:将 curl 输出通过管道传递给
jq时,请使用-s参数并确保已设置 API key
错误处理
排错:API Key 问题
- 检查是否已设置
AISA_API_KEY环境变量:
- 通过简单的测试验证 API key 是否正常工作:
排错:无搜索结果
- 确认你的查询词不为空
- 尝试使用更宽泛的搜索词
- 如果使用了
gl,请确认该国家代码受支持 —— 并非所有 ISO 代码均可用(例如不支持cn)。可尝试省略gl来测试 - 确保每个请求中都包含
engine=youtube - 检查结果是否位于
sections而非videos中(在非英文查询中很常见)
资源
开始使用
- 在 aisa.one 注册并在控制台中创建 API key。
- 在你的终端中设置环境变量:
export AISA_API_KEY="your-key"。 - 使用 安装 下的命令之一安装该 Skill,然后启动新的智能体会话。
相关
YouTube SERP
现有的面向 SERP 的 YouTube Skill。
AIsa YouTube 搜索
AIsa 原生的 YouTube 搜索工作流。
YouTube 搜索端点
YouTube 搜索的端点参考。