如何获取 Brave Search API Key 并执行第一次搜索

Brave API Key 让你可以以编程方式访问 Brave 自有的网页索引：Brave Search 在浏览器中返回的同一批结果，会以 JSON 形式返回，可以直接喂给脚本、仪表盘或 AI Agent。Brave Search API 已经成为让 Agent 获得实时网页访问能力的常见选择；如果这就是你的最终目标，Brave Search MCP server 指南会说明这个 Key 如何接入 Claude 以及其他 MCP 客户端。本文讲的是在此之前的部分：注册账号、选择套餐、生成 Key，并用 curl、Python 和 Apifox 发送一个真实查询。

以下内容来自 Brave 官方控制台文档，时间截至 2026 年 9 月。价格和限制会变化，因此请把文中的数字当作快照，做预算前先查看链接的页面。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

开始前的准备

一个用于注册控制台账号的邮箱地址。
一张信用卡。无论哪个套餐（包括赠送额度的免费档），Brave 都要求绑定信用卡作为反欺诈校验。套餐页面的 FAQ 说明，在免费套餐下信用卡仅用于确认身份。
curl，或者安装了 requests 包的 Python 3，用来运行命令行示例。
Apifox（可选）。如果你想安全地保存 Key，并把请求变成可重复执行的测试，就需要它。第一次调用时可以不用。

第 1 步：注册 Brave Search API 账号

打开 Brave Search API 控制台，用邮箱和密码注册。Brave 会发送一封确认邮件，点击邮件中的链接验证邮箱。在完成验证之前，你无法激活套餐。

该控制台与 Brave 浏览器或 Brave Rewards 的登录账号彼此独立，已有的浏览器账号无法通用，需要重新注册。

第 2 步：选择套餐（免费档有一个坑）

打开控制台中的 Plans 页面。截至 2026 年 9 月，Brave 的定价页面列出以下选项：

套餐	价格	免费额度	速率限制
Search	每 1,000 次请求 $5.00	每月 $5 额度	每秒 50 次请求
Answers	每 1,000 次查询 $4.00，外加每 1,000,000 个输入 token $5.00 和每 1,000,000 个输出 token $5.00	每月 $5 额度	每秒 2 次请求
Spellcheck	每 10,000 次请求 $5.00	每月 $5 额度	每秒 100 次请求
Autosuggest	每 10,000 次请求 $5.00	每月 $5 额度	每秒 100 次请求
Enterprise	定制	联系销售	定制

做网页搜索就选 Search。每月 $5 的额度大约覆盖 1,000 次网页搜索请求，之后才开始产生费用，对开发和轻量的 Agent 场景足够用了。计费为预付制：你先购买额度，每月的免费额度会自动抵扣。

这个坑就在于信用卡。任何套餐（包括带免费额度的）不填卡都无法激活。如果你看过一些老教程，说存在无需绑卡、每月有固定查询配额的免费套餐，那描述的是 Brave 上一代定价。新账号适用上面的额度模型。

选择套餐并填写信用卡信息。套餐会立即在控制台中显示为已激活。

第 3 步：创建 API Key

套餐激活后，打开 API Keys 区域，点击“Add API Key”，给 Key 起一个能说明用途的名字。Brave 的快速上手文档建议使用类似“Production App”或“Development”的命名。每个环境一个 Key 在之后会带来回报：需要吊销某个 Key 时不会影响到其他 Key。

复制 Key 并立即保存到安全的地方。Brave 的认证指南明确指出它绝对不能出现在哪里：客户端代码、公开仓库，或任何公开环境。如果你还不熟悉这类凭据的工作方式，关于什么是 API Key 的入门介绍用几分钟就能讲清这套模型。

第 4 步：发送第一个搜索请求

网页搜索接口是 https://api.search.brave.com/res/v1/web/search。每个请求都必须在 X-Subscription-Token header 中携带 Key。注意这个 header 名称：它不是 Authorization: Bearer，用那种方式发送 Key 会失败。

curl

curl "https://api.search.brave.com/res/v1/web/search?q=openapi+3.1+breaking+changes&count=5&freshness=py" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

count 限制每页返回的结果数（最大 20，默认 20），offset 用于翻页（从 0 开始，最大 9），freshness 按时间范围过滤：pd、pw、pm、py 分别表示过去一天、一周、一个月、一年。其他有用的参数还有 country（两位国家代码）、search_lang 和 safesearch（off、moderate、strict，默认是 moderate）。

Python

import os
import requests

url = "https://api.search.brave.com/res/v1/web/search"
headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": os.environ["BRAVE_API_KEY"],
}
params = {"q": "openapi 3.1 breaking changes", "count": 5, "freshness": "py"}

resp = requests.get(url, headers=headers, params=params, timeout=10)
resp.raise_for_status()
data = resp.json()

for hit in data["web"]["results"]:
    print(hit["title"])
    print(hit["url"])
    print(hit["description"][:120], "\n")

响应中包含一个 query 对象（含 original，以及用于分页的布尔字段 more_results_available）和一个 web.results 数组。每个结果都有 title、url 和 description；设置 extra_snippets=true 后，每个结果最多还能拿到五段额外摘录，这在为模型构建上下文时很有帮助。

Brave 通过可选的 Api-Version header 为 API 做版本控制，格式为 YYYY-MM-DD。不传就使用最新版本；等集成上线后建议固定版本，避免将来的破坏性变更不请自来。

第 5 步：在 Apifox 中测试 Key

把 Key 直接粘到一行 curl 里做第一次调用没问题，但把它留在那里就不合适了。在 Apifox 中，你可以把 Key 存成变量，在所有地方引用它，同时让密钥本身不进入共享的项目。

在 Apifox 项目右上角打开环境管理，添加一个名为 Brave 的环境。创建一个名为 brave_api_key 的变量，把真实的 Key 填到本地值字段，而不是共享值。本地值只保存在你自己的机器上，不会同步给同事；变量参考文档解释了这套双值模型，如果你需要多套环境，Apifox 中环境与私有变量的完整流程还涵盖了 dev、staging 和 prod 的布局。
新建一个 GET 请求，地址为 https://api.search.brave.com/res/v1/web/search。在 Headers 标签页添加 X-Subscription-Token，值为 {{brave_api_key}}。在 Params 中添加 q、count 和 freshness。
点击发送。响应面板会显示 JSON body，header 面板会显示 X-RateLimit-Remaining 和 X-RateLimit-Reset，这样你无需打印任何东西就能观察额度消耗。
添加断言：状态码等于 200，$.web.results 存在且至少有一个元素，$.query.original 与你发送的查询一致。把请求保存到测试场景中。这样一来，Key 轮换或 Brave 侧的变更会表现为一次红色的运行结果，而不是凌晨两点挂掉的 Agent。

速率限制以及 Brave 如何上报

每个响应都会带四个 header，Brave 的速率限制指南中有说明：

X-RateLimit-Limit：你的套餐对应的限制，例如 1, 15000。
X-RateLimit-Policy：同样的限制，附带以秒为单位的时间窗口，例如 1;w=1, 15000;w=2592000（1 秒窗口和 30 天窗口）。
X-RateLimit-Remaining：每个窗口中剩余的额度。
X-RateLimit-Reset：每个窗口重置还需等待的秒数。

有两个细节对预算很重要。第一，指南指出只有成功、非错误的响应才计入配额，所以因为笔误打出的 422 不会吃掉额度。第二，示例 header 里的每秒数字（每秒 1 次请求）只是文档的举例，并不是 Search 套餐标称的每秒 50 次请求。请读取你自己的 header，不要靠假设。

常见错误及处理方式

新生成的 Key 认证失败。Brave 的认证指南要求每个请求都必须携带 X-Subscription-Token，缺失或无效的值会被拒绝。这通常表现为 HTTP 401 以及 token 无效的错误码，不过 Brave 的 API 参考文档并没有明确写出状态码。检查三件事：header 名称是否完全一致（不是 Authorization）、复制 Key 时是否带上了尾部空白、账号上是否有已激活的套餐。如果你不清楚这套方案为什么和 bearer 认证不同，可以看 API Key 与 bearer token 的对比。

422 Unprocessable Entity。某个参数超出范围或格式错误：count 大于 20、offset 大于 9、无法识别的 freshness 值，或者 q 为空。响应 body 遵循 Brave 的错误 schema：

{
  "type": "ErrorResponse",
  "error": {
    "id": "<unique occurrence id>",
    "status": 422,
    "code": "<application error code>",
    "detail": "<what went wrong>",
    "meta": {}
  },
  "time": 0
}

读取 error.detail，它会指出是哪个字段。

429 Too Many Requests。你触发了每秒窗口限制，或者额度用尽。Brave 把 RATE_LIMITED 和 QUOTA_LIMITED 都记录为错误码，所以要确认你遇到的是哪一个：按 X-RateLimit-Reset 中的秒数等待并用退避重试（Brave 建议 1s、2s、4s）可以解决前者，后者只能通过充值额度或等待每月重置来解决。

FAQ

Brave Search API 是免费的吗？

部分免费。每个套餐每月都有 $5 额度，大约相当于 1,000 次 Search 请求，超出后按每 1,000 次请求 $5.00 计费。即使你永远不会超出额度，也没有办法在不绑定信用卡的情况下激活套餐。

网页搜索和 LLM Context 接口需要单独使用不同的 Key 吗？

Brave 的 API 参考文档说该 token 是“为某个产品”生成的，这表明 Key 与它创建时所属的订阅绑定。如果某个 Key 在 /web/search 上可用，却在 /llm/context 或 Answers 接口上失败，先去控制台确认这个 Key 属于哪个套餐，再判断它是不是真的失效了。

我的 Brave API Key 泄露了怎么办？

在 API Keys 区域吊销它，生成一个新的 Key，并更新 Apifox 中的变量，让所有已保存的请求一次性用上新值。然后查清它是怎么泄露的：用密钥扫描工具在仓库和 CI 日志中扫描泄露的 API Key，是确认没有其他东西暴露的最快方式。

不写代码也能试查询吗？

可以。控制台里有一个 Playground 页面用于临时查询，Apifox 的请求构建器也能做到同样的事，额外的好处是请求会被保存下来，之后还能用于测试。

下一步

现在你已经有了账号、已激活的套餐、命名好的 Key，以及一个在三种客户端里都能返回真实结果的请求。接下来，你可以通过 MCP server 把 Key 接入 Agent，或者把 Apifox 测试场景补充完整，让 Key 轮换和额度耗尽在你的用户察觉之前就被发现。这两件事的起点都是今天配置好的同一个 X-Subscription-Token header。