Answers — AI Grounding

Requires API Key: Get one at https://api.search.brave.com
Plan: Included in the Answers plan. See https://api-dashboard.search.brave.com/app/subscriptions/subscribe

When to Use

Use Case	Skill	Why
Quick factual answer (raw context)	INLINECODE0	Single search, returns raw context for YOUR LLM
Fast AI answer with citations

This endpoint (/res/v1/chat/completions) supports two modes:

- Single-search (default): Fast AI-grounded answer from a single search. Supports enable_citations.
Research (enable_research=true): Multi-iteration deep research with progress events and synthesized cited answer.

Quick Start (cURL)

Blocking (Single-Search)

CODEBLOCK0

Streaming with Citations (Single-Search)

CODEBLOCK1

Research Mode

CODEBLOCK2

Endpoint

CODEBLOCK3

Authentication: X-Subscription-Token: <API_KEY> header (or Authorization: Bearer <API_KEY>)

SDK Compatible: Works with OpenAI SDK via INLINECODE8

Two Modes

Feature	Single-Search (default)	Research (`enable_research=true`)
Speed	Fast	Slow
Searches

Parameters

Standard Parameters

Parameter	Type	Required	Default	Description
INLINECODE16	array	Yes	-	Single user message (exactly 1 message)
INLINECODE17

Research Parameters

Parameter	Type	Required	Default	Description
INLINECODE34	bool	No	INLINECODE35	Enable research mode
INLINECODE36

bool | No | true | Enable extended thinking | | research_maximum_number_of_tokens_per_query | int | No | 8192 | Max tokens per query (1024-16384) | | research_maximum_number_of_queries | int | No | 20 | Max total search queries (1-50) | | research_maximum_number_of_iterations | int | No | 4 | Max research iterations (1-5) | | research_maximum_number_of_seconds | int | No | 180 | Time budget in seconds (1-300) | | research_maximum_number_of_results_per_query | int | No | 60 | Results per search query (1-60) |

Constraints (IMPORTANT)

Constraint	Error
INLINECODE48 requires INLINECODE49	"Blocking response doesn't support 'enableresearch' option"
INLINECODE50 incompatible with INLINECODE51

"Research mode doesn't support 'enablecitations' option" | | enable_citations=true requires stream=true | "Blocking response doesn't support 'enable_citations' option" |

OpenAI SDK Usage

Blocking (Single-Search)

CODEBLOCK4

Streaming with Citations (Single-Search)

CODEBLOCK5

Research Mode

CODEBLOCK6

Response Format

Blocking Response (`stream=false`, single-search only)

Standard OpenAI-compatible JSON:

CODEBLOCK7

Streaming Response

SSE response with OpenAI-compatible chunks:

CODEBLOCK8

Streaming Tags by Mode

Single-Search (with `enable_citations=true`)

Tag	Purpose
INLINECODE56	Inline citation references
INLINECODE57

JSON cost/billing data |

Research Mode

Tag	Purpose	Keep?
INLINECODE58	Generated search queries	Debug
INLINECODE59

Usage Tag Format

The <usage> tag contains JSON-stringified cost and token data:

CODEBLOCK9

Use Cases

- Chat interface integration: Drop-in OpenAI SDK replacement with web-grounded answers. Set base_url="https://api.search.brave.com/res/v1".
Deep research / comprehensive topic research: Use research mode (enable_research=true) for complex questions needing multi-source synthesis (e.g., "Compare approaches to nuclear fusion").
OpenAI SDK drop-in: Same SDK, same streaming format — just change base_url and api_key. Works with both sync and async clients.
Cited answers: Enable enable_citations=true in single-search mode for inline citation tags, or use research mode which automatically includes citations in its answer.

Notes

- Timeout: Set client timeout to at least 30s for single-search, 300s (5 min) for research
Single message: The messages array must contain exactly 1 user message
Cost monitoring: Parse the <usage> tag from streaming responses to track costs

答案 — AI 基础事实支撑

需要 API 密钥：请访问 https://api.search.brave.com 获取
套餐：包含在 Answers 套餐中。详见 https://api-dashboard.search.brave.com/app/subscriptions/subscribe

使用场景

使用场景	技能	原因
快速事实性回答（原始上下文）	llm-context	单次搜索，为您的 LLM 返回原始上下文
带引用的快速 AI 回答

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

- 单次搜索（默认）：通过单次搜索快速获得 AI 基础事实支撑的回答。支持 enablecitations。
研究（enableresearch=true）：多次迭代深度研究，包含进度事件和综合引用回答。

快速开始（cURL）

阻塞式（单次搜索）

bash curl -X POST https://api.search.brave.com/res/v1/chat/completions \ -H Content-Type: application/json \ -H X-Subscription-Token: ${BRAVESEARCHAPI_KEY} \ -d { messages: [{role: user, content: 詹姆斯·韦伯太空望远镜是如何工作的？}], model: brave, stream: false }

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

bash curl -X POST https://api.search.brave.com/res/v1/chat/completions \ -H Content-Type: application/json \ -H X-Subscription-Token: ${BRAVESEARCHAPI_KEY} \ -d { messages: [{role: user, content: 聚变能源最近有哪些突破？}], model: brave, stream: true, enable_citations: true }

研究模式

bash curl -X POST https://api.search.brave.com/res/v1/chat/completions \ -H Content-Type: application/json \ -H X-Subscription-Token: ${BRAVESEARCHAPI_KEY} \ -d { messages: [{role: user, content: 比较量子计算方法}], model: brave, stream: true, enable_research: true, researchmaximumnumberofiterations: 3, researchmaximumnumberofseconds: 120 }

端点

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

认证方式：X-Subscription-Token: KEY> 请求头（或 Authorization: Bearer KEY>）

SDK 兼容：通过 base_url=https://api.search.brave.com/res/v1 与 OpenAI SDK 兼容

两种模式

特性	单次搜索（默认）	研究（enable_research=true）
速度	快	慢
搜索次数

参数

标准参数

参数	类型	必需	默认值	描述
messages	数组	是	-	单条用户消息（恰好 1 条消息）
model

字符串 | 是 | - | 使用 brave | | stream | 布尔值 | 否 | true | 启用 SSE 流式传输 | | country | 字符串 | 否 | US | 搜索国家（2 字母国家代码或 ALL） | | language | 字符串 | 否 | en | 响应语言 | | safesearch | 字符串 | 否 | moderate | 搜索安全级别（off、moderate、strict） | | maxcompletiontokens | 整数 | 否 | null | 完成令牌的上限 | | enable_citations | 布尔值 | 否 | false | 包含内联引用标签（仅单次搜索流式传输） | | websearchoptions | 对象 | 否 | null | 兼容 OpenAI；searchcontextsize：low、medium、high |

研究参数

参数	类型	必需	默认值	描述
enableresearch	布尔值	否	false	启用研究模式
researchallow_thinking

布尔值 | 否 | true | 启用扩展思考 | | researchmaximumnumberoftokensperquery | 整数 | 否 | 8192 | 每次查询的最大令牌数（1024-16384） | | researchmaximumnumberofqueries | 整数 | 否 | 20 | 最大总搜索查询数（1-50） | | researchmaximumnumberofiterations | 整数 | 否 | 4 | 最大研究迭代次数（1-5） | | researchmaximumnumberofseconds | 整数 | 否 | 180 | 时间预算（秒）（1-300） | | researchmaximumnumberofresultsperquery | 整数 | 否 | 60 | 每次搜索查询的结果数（1-60） |

约束条件（重要）

约束条件	错误信息
enableresearch=true 需要 stream=true	阻塞式响应不支持 enableresearch 选项
enableresearch=true 与 enablecitations=true 不兼容

研究模式不支持 enable_citations 选项 | | enablecitations=true 需要 stream=true | 阻塞式响应不支持 enablecitations 选项 |

OpenAI SDK 使用

阻塞式（单次搜索）

python 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: 詹姆斯·韦伯太空望远镜是如何工作的？}],
stream=False,
)
print(response.choices[0].message.content)

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

python 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: 可再生能源当前趋势是什么？}],
stream=True,
extrabody={enablecitations: True}
)

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

研究模式

python 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: 比较量子计算方法}],
stream=True,
extra_body={
enable_research: True,
researchmaximumnumberofiterations: 3,
researchmaximumnumberofseconds: 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：

json
{
id: chatcmpl-...,
object: chat.completion,
choices: [{message

基于AI的答案

基于AI的答案

Answers — AI Grounding

When to Use

Quick Start (cURL)

Blocking (Single-Search)

Streaming with Citations (Single-Search)

Research Mode

Endpoint

Two Modes

Parameters

Standard Parameters

Research Parameters

Constraints (IMPORTANT)

OpenAI SDK Usage

Blocking (Single-Search)

Streaming with Citations (Single-Search)

Research Mode

Response Format

Blocking Response (stream=false, single-search only)

Streaming Response

Streaming Tags by Mode

Single-Search (with enable_citations=true)

Research Mode

Usage Tag Format

Use Cases

Notes

答案 — AI 基础事实支撑

使用场景

快速开始（cURL）

阻塞式（单次搜索）

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

研究模式

端点

两种模式

参数

标准参数

研究参数

约束条件（重要）

OpenAI SDK 使用

阻塞式（单次搜索）

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

研究模式

响应格式

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

标签

通过对话安装

方式一：安装 SkillHub 和技能

方式二：设置 SkillHub 为优先技能安装源

通过命令行安装

下载

相关推荐

self-improvement

self-improvement

self-improvement

self-improvement

Blocking Response (`stream=false`, single-search only)

Single-Search (with `enable_citations=true`)