brave-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Brave Search API

Overview

概述

Search the web, images, and news using Brave's privacy-focused Search API. Also supports AI Grounding for cited answers via OpenAI SDK compatibility.

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

Prerequisites

前提条件

API Key required. Get one at https://api-dashboard.search.brave.com

bash

export BRAVE_API_KEY="your-api-key"

Free tier: 2,000 queries/month. Pro plans unlock Local POI search and AI Grounding.

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

bash

export BRAVE_API_KEY="your-api-key"

免费层级：每月2000次查询。专业版计划解锁本地POI搜索和AI Grounding功能。

When to Use

使用场景

Searching the web for current information
Finding images on a topic
Getting recent news articles
AI-grounded answers with citations
Autocomplete suggestions
Location/POI searches (Pro plan)

搜索网页获取当前信息
查找特定主题的图片
获取近期新闻文章
带引用的AI锚定答案
自动补全建议
地点/POI搜索（专业版计划）

High-Throughput Usage

高吞吐量使用方式

Go wide, go fast. This API supports high concurrency—up to 50 requests/second. Don't hold back:

Fire searches in parallel. Need to research 10 different topics? Launch 10 searches simultaneously. Use multiple Bash tool calls in a single message.
Use subagents for heavy results. When expecting lots of context (many results, extra snippets, research mode), dispatch a subagent to run the search and synthesize findings. This preserves your main context window.
Batch related queries. Searching for competitors, alternatives, or multiple aspects of a topic? Run them all at once.

dot

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;
}

When to use subagents:

Searching for many sources on a topic (launch search subagent, return summary)
Deep research with AI Grounding (high token usage, let subagent handle)
Comparing multiple options (run parallel searches, subagent synthesizes)

When to search directly:

Quick single queries where you need the raw URLs/snippets
Low result counts where context isn't a concern

广泛、快速调用。该API支持高并发——最高每秒50次请求。无需受限：

并行发起搜索。需要研究10个不同主题？同时发起10次搜索。在单条消息中使用多个Bash工具调用。
使用子Agent处理大量结果。当预期会有大量上下文（多结果、额外片段、研究模式）时，分派一个子Agent来运行搜索并整合结果。这样可以保留主上下文窗口。
批量处理相关查询。搜索竞品、替代方案或某个主题的多个方面？一次性全部运行。

dot

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/片段的快速单次查询
结果数量少，无需担心上下文的场景

Quick Reference

快速参考

Task	Command
Web search	`brave-search web "query"`
Image search	`brave-search images "query"`
News search	`brave-search news "query"`
AI answer	`brave-search ai "question"`
Suggestions	`brave-search suggest "partial query"`
Check key	`brave-search check-key`

任务	命令
网页搜索	`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 Endpoints

API端点

API	Endpoint	Plan
Web Search	`/res/v1/web/search`	Free
Image Search	`/res/v1/images/search`	Free
News Search	`/res/v1/news/search`	Free
Suggest	`/res/v1/suggest/search`	Free
AI Grounding	`/res/v1/chat/completions`	AI Grounding
Local POI	`/res/v1/local/pois`	Pro
Summarizer	`/res/v1/summarizer/search`	Pro

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
本地POI	`/res/v1/local/pois`	专业版
摘要工具	`/res/v1/summarizer/search`	专业版

Common Parameters

通用参数

Web Search

网页搜索

bash

undefined

bash

undefined

Basic search

基础搜索

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

Filter by freshness (pd=24h, pw=7d, pm=31d, py=365d)

按时效性过滤（pd=24小时，pw=7天，pm=31天，py=365天）

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

undefined

brave-search web "query" --filter web,news

undefined

Image Search

图片搜索

bash

undefined

bash

undefined

Basic image search

基础图片搜索

brave-search images "mountain sunset"

With safe search

开启安全搜索

brave-search images "landscape" --safesearch strict --count 20

undefined

brave-search images "landscape" --safesearch strict --count 20

undefined

News Search

新闻搜索

bash

undefined

bash

undefined

近期新闻

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

News with freshness filter

带时效性过滤的新闻

brave-search news "election results" --freshness pd

undefined

brave-search news "election results" --freshness pd

undefined

AI Grounding (Cited Answers)

AI Grounding（带引用的答案）

bash

undefined

bash

undefined

Get an AI answer with citations

获取带引用的AI答案

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

undefined

brave-search ai "Compare React and Vue in 2024" --research

undefined

Workflow

工作流

dot

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;
}

dot

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;
}

Response Structure

响应结构

Web Search Results

网页搜索结果

json

{
  "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"
  }
}

json

{
  "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 Response

AI Grounding响应

Returns OpenAI-compatible format with inline citations:

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

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

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

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

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

Common Options

通用选项

Option	Values	Description
`--count`	1-20 (web), 1-200 (images)	Number of results
`--country`	US, GB, DE, FR, etc.	Search region
`--lang`	en, de, fr, es, etc.	Search language
`--safesearch`	off, moderate, strict	Adult content filter
`--freshness`	pd, pw, pm, py	Time filter
`--json`	flag	Output raw JSON

选项	取值	描述
`--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

Error Handling

错误处理

Error	Cause	Fix
401 Unauthorized	Invalid/missing API key	Check `BRAVE_API_KEY`
429 Rate Limited	Too many requests	Wait or upgrade plan
422 Validation	Invalid parameters	Check parameter values

错误	原因	修复方案
401 Unauthorized	API密钥无效/缺失	检查 `BRAVE_API_KEY`
429 Rate Limited	请求过多	等待或升级计划
422 Validation	参数无效	检查参数取值

Rate Limits

速率限制

Free: 1 req/sec, 2,000/month
Pro: Higher limits, check dashboard
Response headers show remaining quota:
```
X-RateLimit-Remaining
```

免费版：每秒1次请求，每月2000次
专业版：更高限制，请查看控制台
响应头显示剩余配额：
```
X-RateLimit-Remaining
```

Common Mistakes

常见错误

Mistake	Fix
API key not set	`export BRAVE_API_KEY="..."`
Wrong endpoint for plan	Check subscription at dashboard
Too many results	Web max is 20, use offset for pagination
No AI grounding	Requires AI Grounding subscription

错误	修复方案
未设置API密钥	`export BRAVE_API_KEY="..."`
计划不支持的端点	在控制台检查订阅情况
结果数量过多	网页搜索最多20条，使用offset进行分页
无AI Grounding功能	需要订阅AI Grounding服务

brave-search

Original

Translation

Brave Search API

Brave Search API

Overview

概述

Prerequisites

前提条件

When to Use

使用场景

High-Throughput Usage

高吞吐量使用方式

Quick Reference

快速参考

API Endpoints

API端点

Common Parameters

通用参数

Web Search

网页搜索

Basic search

基础搜索

Filter by freshness (pd=24h, pw=7d, pm=31d, py=365d)

按时效性过滤（pd=24小时，pw=7天，pm=31天，py=365天）

Filter by country and language

按国家和语言过滤

Safe search (off, moderate, strict)

安全搜索（关闭、中等、严格）

Get extra snippets

获取额外片段

Filter result types (web, news, videos, images, discussions)

过滤结果类型（网页、新闻、视频、图片、讨论）

Image Search

图片搜索

Basic image search

基础图片搜索

With safe search

开启安全搜索

News Search

新闻搜索

Recent news

近期新闻

News with freshness filter

带时效性过滤的新闻

AI Grounding (Cited Answers)

AI Grounding（带引用的答案）

Get an AI answer with citations

获取带引用的AI答案

Enable deep research (multiple searches, slower)

开启深度研究（多次搜索，速度较慢）

Workflow

工作流

Response Structure

响应结构

Web Search Results

网页搜索结果

AI Grounding Response

AI Grounding响应

Common Options

通用选项

Error Handling

错误处理

Rate Limits

速率限制

Common Mistakes

常见错误