> ## Documentation Index
> Fetch the complete documentation index at: https://aisa.one/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# YouTube SERP

> 面向自治 Agent 的 YouTube 搜索，返回排序结果和丰富元数据。可用于内容缺口分析、竞品监控、关键词研究，以及按地区/语言进行受众研究。

[在 GitHub 上查看 ->](https://github.com/AIsa-team/agent-skills/tree/main/youtube-serp)

**面向自治 Agent 的 YouTube 搜索结果和丰富元数据。** 一个 `AISA_API_KEY` 即可返回排序视频、播放量、发布时间和缩略图，并支持按国家和语言过滤。

## 安装

如果还没有安装 AIsa CLI，请先安装：

```bash theme={null}
npm install -g @aisa-one/cli
```

然后安装该技能：

```bash theme={null}
aisa skills install youtube-serp
```

## Agent 可以用它做什么？

<CardGroup cols={2}>
  <Card title="内容缺口分析" icon="chart-gantt">
    “找出 ‘AI agent tutorial’ 当前排名靠前、但我们频道还没有覆盖的内容。”
  </Card>

  <Card title="竞品监控" icon="eye">
    “跟踪这个细分领域前 5 个频道的新上传视频。”
  </Card>

  <Card title="关键词研究" icon="key">
    “哪些 ‘RAG’ 变体能带来最高播放量？”
  </Card>

  <Card title="区域趋势" icon="earth-americas">
    “比较日本（jp/ja）和美国（us/en）的热门机器学习内容。”
  </Card>

  <Card title="受众研究" icon="users">
    “哪些缩略图和标题适合 agent demo？”
  </Card>

  <Card title="趋势发现" icon="fire">
    “标记相对频道基线速度异常的视频。”
  </Card>
</CardGroup>

## 核心能力

* **关键词搜索** — 对任意查询返回排序 YouTube 结果
* **区域定向** — `gl`（国家：`us`、`jp`、`cn` 等）和 `hl`（界面语言：`en`、`ja`、`zh-CN` 等）
* **丰富元数据** — 标题、频道、播放量、发布日期、时长和缩略图
* **分页** — 使用过滤 token 跳转到第一页之后的结果

## 快速开始

```bash theme={null}
export AISA_API_KEY="your-key"
```

### 基础搜索

```bash theme={null}
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+agents+tutorial" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

### 地区 + 语言

```bash theme={null}
# 日本机器学习内容，日语界面
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=machine+learning&gl=jp&hl=ja" \
  -H "Authorization: Bearer $AISA_API_KEY"

# 美国 AI 趋势，英语界面
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+trends+2026&gl=us&hl=en" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

### 分页

响应会包含分页 token，可传回端点抓取下一页：

```bash theme={null}
curl "https://api.aisa.one/apis/v1/youtube/search?engine=youtube&q=AI+agents&sp=NEXT_PAGE_TOKEN" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

## Python 客户端

```bash theme={null}
# 基础搜索
python3 scripts/youtube_client.py search --query "autonomous agents"

# 指定国家
python3 scripts/youtube_client.py search --query "coding tutorial" --country us

# 指定国家 + 语言
python3 scripts/youtube_client.py search --query "機械学習" --country jp --lang ja
```

## 端点参考

| Endpoint          | Method | 用途                                                         |
| ----------------- | ------ | ---------------------------------------------------------- |
| `/youtube/search` | GET    | [YouTube search](/api-reference/search/get_youtube-search) |

**常用参数：**

* `engine` — 固定为 `youtube`
* `q` — 搜索查询（必填）
* `gl` — 国家代码（`us`、`jp`、`cn` 等）
* `hl` — 语言代码（`en`、`ja`、`zh-CN` 等）
* `sp` — 分页 token

## 开始使用

1. 在 [aisa.one](https://aisa.one) 注册（新账户有 \$2 免费额度）。
2. 从控制台生成 API key。
3. `export AISA_API_KEY="your-key"` 并安装技能：
   ```bash theme={null}
   npm install -g @aisa-one/cli
   aisa skills install youtube-serp
   ```

## 相关

<CardGroup cols={3}>
  <Card title="YouTube Search endpoint" icon="youtube" href="/api-reference/search/get_youtube-search">
    完整端点参考和交互式 Playground。
  </Card>

  <Card title="Multi-source Search" icon="magnifying-glass" href="/agent-skills/search">
    将 YouTube search 与 web、scholar、Tavily 组合使用。
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/errors">
    处理 YouTube API 层错误。
  </Card>
</CardGroup>