answers

答案 — AI 溯源

需要 API 密钥：前往 https://api.search.brave.com 获取

套餐：包含在 Answers 套餐中。请参阅 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

适用场景

使用场景	技能	原因
快速获取事实答案（原始上下文）	llm-context	单次搜索，为你的大模型返回原始上下文
快速获取带引用的 AI 答案	answers（单次搜索）	流式传输、包含引用
多次搜索的深入研究	answers（研究模式）	迭代式深入研究，生成综合性的带引用答案

此端点（/res/v1/chat/completions）支持两种模式：

• 单次搜索（默认）：通过单次搜索快速获取 AI 溯源答案。支持 enable_citations。
• 研究（enable_research=true）：多轮迭代深入研究，包含进度事件并生成综合性的带引用答案。

快速开始（cURL）

阻塞式（单次搜索）

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "How does the James Webb Space Telescope work?"}],
    "stream": false
  }'

带引用的流式传输（单次搜索）

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "What are recent breakthroughs in fusion energy?"}],
    "stream": true,
    "enable_citations": true
  }'

研究模式

curl -X POST "https://api.search.brave.com/res/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "X-Subscription-Token: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "Compare quantum computing approaches"}],
    "stream": true,
    "enable_research": true,
    "research_maximum_number_of_iterations": 3,
    "research_maximum_number_of_seconds": 120
  }'

端点

POST https://api.search.brave.com/res/v1/chat/completions

身份验证：使用 X-Subscription-Token: <API_KEY> 标头（或 Authorization: Bearer <API_KEY>）

SDK 兼容性：通过 base_url="https://api.search.brave.com/res/v1" 与 OpenAI SDK 配合使用

两种模式

功能	单次搜索（默认）	研究（enable_research=true）
速度	快	慢
搜索次数	1	多次（迭代）
流式传输	可选（stream=true/false）	必需（stream=true）
引用	enable_citations=true（仅限流式传输）	内置（位于 <answer> 标签中）
进度事件	否	是（<progress> 标签）
阻塞式响应	是（stream=false）	否

参数

标准参数

参数	类型	必需	默认值	描述
messages	array	是	-	单条用户消息（恰好 1 条消息）
stream	bool	否	true	启用 SSE 流式传输
country	string	否	"US"	搜索国家（2 位国家代码或 ALL）
language	string	否	"en"	响应语言
safesearch	string	否	"moderate"	搜索安全级别（off、moderate、strict）
max_completion_tokens	int	否	null	完成令牌数上限
enable_citations	bool	否	false	包含行内引用标签（仅限单次搜索的流式传输）
web_search_options	object	否	null	兼容 OpenAI；search_context_size：low、medium、high

研究参数

参数	类型	必需	默认值	描述
enable_research	bool	否	false	启用研究模式
research_allow_thinking	bool	否	true	启用扩展思考
research_maximum_number_of_tokens_per_query	int	否	8192	每次查询的最大令牌数（1024-16384）
research_maximum_number_of_queries	int	否	20	搜索查询总数上限（1-50）
research_maximum_number_of_iterations	int	否	4	研究迭代次数上限（1-5）
research_maximum_number_of_seconds	int	否	180	时间预算（秒，1-300）
research_maximum_number_of_results_per_query	int	否	60	每次搜索查询的结果数（1-60）

约束（重要）

约束	错误
enable_research=true 要求 stream=true	"Blocking response doesn't support 'enable_research' option"
enable_research=true 与 enable_citations=true 不兼容	"Research mode doesn't support 'enable_citations' option"
enable_citations=true 要求 stream=true	"Blocking response doesn't support 'enable_citations' option"

OpenAI SDK 用法

阻塞式（单次搜索）

from openai import OpenAI

client = OpenAI(
    base_url="https://api.search.brave.com/res/v1",
    api_key="your-brave-api-key",
)

response = client.chat.completions.create(
    model="brave",
    messages=[{"role": "user", "content": "How does the James Webb Space Telescope work?"}],
    stream=False,
)
print(response.choices[0].message.content)

带引用的流式传输（单次搜索）

from openai import OpenAI

client = OpenAI(
    base_url="https://api.search.brave.com/res/v1",
    api_key="your-brave-api-key",
)

stream = client.chat.completions.create(
    model="brave",
    messages=[{"role": "user", "content": "What are the current trends in renewable energy?"}],
    stream=True,
    extra_body={"enable_citations": True}
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

研究模式

from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.search.brave.com/res/v1",
    api_key="your-brave-api-key",
)

stream = await client.chat.completions.create(
    model="brave",
    messages=[{"role": "user", "content": "Compare quantum computing approaches"}],
    stream=True,
    extra_body={
        "enable_research": True,
        "research_maximum_number_of_iterations": 3,
        "research_maximum_number_of_seconds": 120
    }
)

async for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

响应格式

阻塞式响应（stream=false，仅限单次搜索）

标准的 OpenAI 兼容 JSON：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "choices": [{"message": {"role": "assistant", "content": "The James Webb Space Telescope works by..."}, "index": 0, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 10, "completion_tokens": 50, "total_tokens": 60}
}

流式响应

包含 OpenAI 兼容数据块的 SSE 响应：

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"Based on"},"index":0}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":" recent research"},"index":0}]}

data: [DONE]

各模式的流式标签

单次搜索（设置 enable_citations=true）

Tag	用途
<citation>	行内引用参考
<usage>	JSON 费用／计费数据

研究模式

Tag	用途	保留？
<queries>	生成的搜索查询	调试
<analyzing>	URL 数量（详细）	调试
<thinking>	URL 选择理由	调试
<progress>	统计信息：时间、迭代次数、查询、已分析的 URL、令牌	监控
<blindspots>	识别出的知识盲区	是
<answer>	最终综合回答（仅输出最终回答；中间草稿会被丢弃）	是
<usage>	JSON 费用／计费数据（包含在流式响应末尾）	是

Usage 标签格式

<usage> 标签包含 JSON 字符串化的费用和令牌数据：

<usage>{"X-Request-Requests":1,"X-Request-Queries":8,"X-Request-Tokens-In":15000,"X-Request-Tokens-Out":2000,"X-Request-Requests-Cost":0.005,"X-Request-Queries-Cost":0.032,"X-Request-Tokens-In-Cost":0.075,"X-Request-Tokens-Out-Cost":0.01,"X-Request-Total-Cost":0.122}</usage>

使用场景

• 聊天界面集成：可直接替换 OpenAI SDK，提供基于网络信息的回答。设置 base_url="https://api.search.brave.com/res/v1"。
• 深度研究／全面的主题研究：对于需要综合多个来源的复杂问题（例如“比较核聚变的不同方法”），使用研究模式（enable_research=true）。
• 直接替换 OpenAI SDK：SDK 相同，流式格式相同——只需更改 base_url 和 api_key。同步和异步客户端均可使用。
• 带引用的回答：在单次搜索模式中启用 enable_citations=true，以获取行内引用标签；也可以使用会自动在回答中包含引用的研究模式。

注意事项

• 超时：单次搜索的客户端超时至少设为 30s，研究模式至少设为 300s（5 min）
• 单条消息：messages 数组必须且只能包含 1 条用户消息
• 费用监控：解析流式响应中的 <usage> 标签以跟踪费用