Back to Details

brave-search

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Brave Search API

Brave Search API

Use the Brave Search API via direct 
curl
calls to perform privacy-focused web searches with no user tracking.
Official docs: 
https://api.search.brave.com/app/documentation
通过直接调用
curl
来使用Brave Search API，执行注重隐私的网页搜索，无用户追踪。
官方文档：
https://api.search.brave.com/app/documentation

When to Use

适用场景

Use this skill when you need to:
  • Web search with privacy-focused results
  • Image search for finding images
  • Video search for video content
  • News search for current events
  • AI-powered summaries of search results
当你需要以下功能时使用该技能：
  • 网页搜索：获取注重隐私的搜索结果
  • 图片搜索：查找图片内容
  • 视频搜索：查找视频内容
  • 新闻搜索：获取时事资讯
  • AI生成摘要：搜索结果的AI驱动摘要

Prerequisites

前置条件

  1. Sign up at Brave Search API
  2. Subscribe to a plan (Free tier available, credit card required for anti-fraud)
  3. Get your API key from the Dashboard
bash
export BRAVE_API_KEY="your-api-key"
  1. 在Brave Search API注册账号
  2. 订阅套餐（提供免费层级，为反欺诈需绑定信用卡）
  3. 从控制台获取API密钥
bash
export BRAVE_API_KEY="your-api-key"

Pricing

定价方案

PlanPriceRate LimitMonthly Cap
Free$01 query/sec2,000 queries
Base$5/100020 query/sec20M queries
Pro$9/100050 query/secUnlimited
Important: When using 
$VAR
in a command that pipes to another command, wrap the command containing 
$VAR
in 
bash -c '...'
. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
套餐价格请求速率限制月度限额
免费版$01次查询/秒2000次查询
基础版$5/1000次20次查询/秒2000万次查询
专业版$9/1000次50次查询/秒无限制
重要提示：当在包含管道的命令中使用
$VAR
时，请将包含
$VAR
的命令用
bash -c '...'
包裹。由于Claude Code的bug，直接使用管道时环境变量会被静默清除。
bash
bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'

How to Use

使用方法

All examples below assume you have 
BRAVE_API_KEY
set.
The base URL for the API is:
  • https://api.search.brave.com/res/v1
Authentication uses the 
X-Subscription-Token
header.
以下所有示例均假设你已设置好
BRAVE_API_KEY
。
API的基础URL为：
  • https://api.search.brave.com/res/v1
认证使用
X-Subscription-Token
请求头。

1. Basic Web Search

1. 基础网页搜索

Search the web with a query:
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search?q=artificial+intelligence" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}"' | jq '.web.results[:3] | .[] | {title, url, description}
使用关键词进行网页搜索：
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search?q=artificial+intelligence" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}"' | jq '.web.results[:3] | .[] | {title, url, description}

2. Web Search with Parameters

2. 带参数的网页搜索

Customize search with country, language, and result count:
Write to 
/tmp/brave_query.txt
:
best restaurants
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "country=us" -d "search_lang=en" -d "count=5"' | jq '.web.results[] | {title, url}'
Parameters:
  • q
    : Search query (required, max 400 chars / 50 words)
  • country
    : Two-letter country code (e.g., 
    us
    , 
    gb
    , 
    jp
    )
  • search_lang
    : Language code (e.g., 
    en
    , 
    zh
    , 
    ja
    )
  • count
    : Results per page (1-20, default: 10)
  • offset
    : Pagination offset (0-9, default: 0)
通过国家、语言和结果数量自定义搜索：
在
/tmp/brave_query.txt
中写入：
best restaurants
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "country=us" -d "search_lang=en" -d "count=5"' | jq '.web.results[] | {title, url}'
参数说明：
  • q
    ：搜索查询（必填，最多400字符/50个单词）
  • country
    ：两位国家代码（如
    us
    、
    gb
    、
    jp
    ）
  • search_lang
    ：语言代码（如
    en
    、
    zh
    、
    ja
    ）
  • count
    ：每页结果数（1-20，默认：10）
  • offset
    ：分页偏移量（0-9，默认：0）

3. Safe Search Filter

3. 安全搜索过滤

Control explicit content filtering:
Write to 
/tmp/brave_query.txt
:
programming tutorials
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "safesearch=strict"' | jq '.web.results[:3] | .[] | {title, url}
Options: 
off
, 
strict
(Note: Image/Video search only supports 
off
and 
strict
)
控制露骨内容过滤：
在
/tmp/brave_query.txt
中写入：
programming tutorials
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "safesearch=strict"' | jq '.web.results[:3] | .[] | {title, url}
可选值： 
off
、
strict
（注意：图片/视频搜索仅支持
off
和
strict
）

4. Freshness Filter

4. 时效性过滤

Filter results by time:
Write to 
/tmp/brave_query.txt
:
tech news
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "freshness=pd"' | jq '.web.results[:3] | .[] | {title, url, age}
Options:
  • pd
    : Past day (24 hours)
  • pw
    : Past week
  • pm
    : Past month
  • py
    : Past year
  • YYYY-MM-DDtoYYYY-MM-DD
    : Custom date range
按时间过滤搜索结果：
在
/tmp/brave_query.txt
中写入：
tech news
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "freshness=pd"' | jq '.web.results[:3] | .[] | {title, url, age}
可选值：
  • pd
    ：过去24小时
  • pw
    ：过去一周
  • pm
    ：过去一个月
  • py
    ：过去一年
  • YYYY-MM-DDtoYYYY-MM-DD
    ：自定义日期范围

5. Image Search

5. 图片搜索

Search for images:
Write to 
/tmp/brave_query.txt
:
sunset beach
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/images/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=5" -d "safesearch=strict"' | jq '.results[] | {title, url: .properties.url, thumbnail: .thumbnail.src}
Image search supports up to 200 results per request.
搜索图片内容：
在
/tmp/brave_query.txt
中写入：
sunset beach
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/images/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=5" -d "safesearch=strict"' | jq '.results[] | {title, url: .properties.url, thumbnail: .thumbnail.src}
图片搜索单次请求最多支持200条结果。

6. Video Search

6. 视频搜索

Search for videos:
Write to 
/tmp/brave_query.txt
:
learn python
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/videos/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=5"' | jq '.results[] | {title, url, duration}
Video search supports up to 50 results per request.
搜索视频内容：
在
/tmp/brave_query.txt
中写入：
learn python
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/videos/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=5"' | jq '.results[] | {title, url, duration}
视频搜索单次请求最多支持50条结果。

7. News Search

7. 新闻搜索

Search for recent news articles:
Write to 
/tmp/brave_query.txt
:
technology
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/news/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=3"' | jq '.results[:3] | .[] | {title, url, age}
News search defaults to past day (
pd
) freshness.
搜索近期新闻文章：
在
/tmp/brave_query.txt
中写入：
technology
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/news/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=3"' | jq '.results[:3] | .[] | {title, url, age}
新闻搜索默认时效性为过去24小时（
pd
）。

8. Pagination

8. 分页查询

Get more results with offset:
Write to 
/tmp/brave_query.txt
:
machine learning
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=10" -d "offset=1"' | jq '.web.results[] | {title, url}
offset=1
skips the first page of results.
通过偏移量获取更多结果：
在
/tmp/brave_query.txt
中写入：
machine learning
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}" -G --data-urlencode "q@/tmp/brave_query.txt" -d "count=10" -d "offset=1"' | jq '.web.results[] | {title, url}
offset=1
表示跳过第一页结果。

9. Get Raw JSON Response

9. 获取原始JSON响应

View the full response structure:
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search?q=test" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}"' | jq 'keys'
Response includes: 
query
, 
mixed
, 
type
, 
web
, 
videos
, 
news
, etc.
查看完整响应结构：
bash
bash -c 'curl -s "https://api.search.brave.com/res/v1/web/search?q=test" -H "Accept: application/json" -H "X-Subscription-Token: ${BRAVE_API_KEY}"' | jq 'keys'
响应包含：
query
、
mixed
、
type
、
web
、
videos
、
news
等字段。

Response Structure

响应结构

Web Search Response

网页搜索响应

json
{
  "query": { "original": "search term" },
  "web": {
  "results": [
  {
  "title": "Page Title",
  "url": "https://example.com",
  "description": "Page description...",
  "age": "2 days ago"
  }
  ]
  }
}
json
{
  "query": { "original": "search term" },
  "web": {
  "results": [
  {
  "title": "Page Title",
  "url": "https://example.com",
  "description": "Page description...",
  "age": "2 days ago"
  }
  ]
  }
}

Image Search Response

图片搜索响应

json
{
  "results": [
  {
  "title": "Image Title",
  "properties": { "url": "https://..." },
  "thumbnail": { "src": "https://..." }
  }
  ]
}
json
{
  "results": [
  {
  "title": "Image Title",
  "properties": { "url": "https://..." },
  "thumbnail": { "src": "https://..." }
  }
  ]
}

Guidelines

使用准则

  1. URL encode queries: Use 
    --data-urlencode
    for special characters
  2. Respect rate limits: Free tier is 1 query/second
  3. Use freshness for news: Time-sensitive searches benefit from 
    pd
    or 
    pw
  4. Pagination limit: Maximum offset is 9 (100 results total with count=10)
  5. Pro plan for local: Local business search requires Pro subscription
  6. No tracking: Brave doesn't track users or store search history
  1. URL编码查询内容：对特殊字符使用
    --data-urlencode
  2. 遵守速率限制：免费版限制为1次查询/秒
  3. 新闻搜索使用时效性参数：时间敏感的搜索推荐使用
    pd
    或
    pw
  4. 分页限制：最大偏移量为9（配合count=10时最多获取100条结果）
  5. 本地搜索需专业版：本地商家搜索需要订阅专业版套餐
  6. 无追踪保障：Brave不会追踪用户或存储搜索历史