brave-search

Brave Search API

概述

使用 Brave 的注重隐私的 Search API 搜索网页、图片和新闻。还支持通过 OpenAI SDK 兼容性实现 AI Grounding，提供附带引用的答案。

前提条件

需要 API 密钥。 请在 https://api-dashboard.search.brave.com 获取。

export BRAVE_API_KEY="your-api-key"

免费套餐：每月 2,000 次查询。Pro 套餐可解锁 Local POI 搜索和 AI Grounding。

适用场景

• 搜索当前信息
• 查找某个主题的图片
• 获取近期新闻文章
• 获取带引用的 AI Grounding 答案
• 自动补全建议
• 搜索位置/POI（Pro 套餐）

高吞吐量用法

广泛搜索，快速执行。 此 API 支持高并发，每秒最多可处理 50 个请求。尽管使用：

• 并行发起搜索。 需要研究 10 个不同主题？同时启动 10 次搜索。在同一条消息中调用多个 Bash 工具。
• 结果较多时使用子 Agent。 预计会有大量上下文（许多结果、额外摘要、研究模式）时，派遣子 Agent 执行搜索并综合结果。这样可以保留主上下文窗口。
• 批量处理相关查询。 搜索竞争对手、替代方案或某个主题的多个方面？一次性全部执行。

digraph parallel_search {
    rankdir=LR;
    node [shape=box];

    task [label="Research task"];
    q1 [label="Query 1"];
    q2 [label="Query 2"];
    q3 [label="Query 3"];
    subagent [label="Subagent\n(preserves context)"];
    synthesize [label="Synthesized\nfindings"];

    task -> q1;
    task -> q2;
    task -> q3;
    q1 -> subagent [style=dashed];
    q2 -> subagent [style=dashed];
    q3 -> subagent [style=dashed];
    subagent -> synthesize;
}

适合使用子 Agent 的场景：

• 搜索某个主题的多个来源（启动搜索子 Agent，并返回摘要）
• 使用 AI Grounding 进行深入研究（会消耗大量 token，可交由子 Agent 处理）
• 比较多个选项（并行搜索，由子 Agent 综合结果）

适合直接搜索的场景：

• 需要原始 URL/摘要的快速单次查询
• 结果较少，不必担心上下文占用

快速参考

任务	命令
网页搜索	brave-search web "query"
图片搜索	brave-search images "query"
新闻搜索	brave-search news "query"
AI 答案	brave-search ai "question"
建议	brave-search suggest "partial query"
检查密钥	brave-search check-key

API 端点

API	端点	套餐
网页搜索	/res/v1/web/search	免费
图片搜索	/res/v1/images/search	免费
新闻搜索	/res/v1/news/search	免费
建议	/res/v1/suggest/search	免费
AI Grounding	/res/v1/chat/completions	AI Grounding
Local POI	/res/v1/local/pois	Pro
摘要生成器	/res/v1/summarizer/search	Pro

常用参数

网页搜索

# Basic search
brave-search web "python async tutorial" --count 10

# Filter by freshness (pd=24h, pw=7d, pm=31d, py=365d)
brave-search web "latest news" --freshness pd

# Filter by country and language
brave-search web "local restaurants" --country US --lang en

# Safe search (off, moderate, strict)
brave-search web "query" --safesearch strict

# Get extra snippets
brave-search web "query" --extra-snippets

# Filter result types (web, news, videos, images, discussions)
brave-search web "query" --filter web,news

图片搜索

# Basic image search
brave-search images "mountain sunset"

# With safe search
brave-search images "landscape" --safesearch strict --count 20

新闻搜索

# Recent news
brave-search news "AI developments" --count 10

# News with freshness filter
brave-search news "election results" --freshness pd

AI Grounding（附带引用的答案）

# Get an AI answer with citations
brave-search ai "What is the tallest building in the world?"

# Enable deep research (multiple searches, slower)
brave-search ai "Compare React and Vue in 2024" --research

工作流

digraph brave_search {
    rankdir=TB;
    node [shape=box];

    need [label="What do you need?" shape=diamond];
    web [label="Web Search\nbrave.py web"];
    images [label="Image Search\nbrave.py images"];
    news [label="News Search\nbrave.py news"];
    ai [label="AI Answer\nbrave.py ai"];

    results [label="Parse JSON results"];
    cite [label="Include citations\nfor AI answers"];

    need -> web [label="web pages"];
    need -> images [label="images"];
    need -> news [label="recent news"];
    need -> ai [label="cited answer"];

    web -> results;
    images -> results;
    news -> results;
    ai -> cite;
}

响应结构

网页搜索结果

{
  "web": {
    "results": [
      {
        "title": "Page Title",
        "url": "https://example.com",
        "description": "Snippet from the page...",
        "extra_snippets": ["Additional context..."]
      }
    ]
  },
  "query": {
    "original": "search query",
    "altered": "modified query if spellchecked"
  }
}

AI Grounding 响应

返回 OpenAI 兼容格式，并包含内联引用：

The tallest building is the Burj Khalifa[1] at 828 meters...

[1] https://source-url.com

常用选项

选项	值	说明
--count	1-20（网页），1-200（图片）	结果数量
--country	US, GB, DE, FR 等	搜索区域
--lang	en, de, fr, es 等	搜索语言
--safesearch	off, moderate, strict	成人内容过滤器
--freshness	pd, pw, pm, py	时间筛选
--json	标志	输出原始 JSON

错误处理

错误	原因	解决方法
401 Unauthorized	API 密钥无效或缺失	检查 BRAVE_API_KEY
429 Rate Limited	请求过多	等待或升级套餐
422 Validation	参数无效	检查参数值

速率限制

• 免费：每秒 1 个请求，每月 2,000 次
• Pro：限制更高，请查看控制面板
• 响应头会显示剩余配额：X-RateLimit-Remaining

常见错误

错误	解决方法
未设置 API 密钥	export BRAVE_API_KEY="..."
套餐对应的端点错误	在控制面板查看订阅
结果过多	网页搜索最多返回 20 条，可使用 offset 翻页
没有 AI Grounding	需要订阅 AI Grounding