Back to Details

answers

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Answers — AI Grounding

基于AI的事实性回答（Answers）

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
需要API密钥：请前往https://api.search.brave.com获取
适用套餐：包含在Answers套餐中。详情请见https://api-dashboard.search.brave.com/app/subscriptions/subscribe

When to Use

适用场景

Use CaseSkillWhy
Quick factual answer (raw context)
llm-context
Single search, returns raw context for YOUR LLM
Fast AI answer with citations
answers
 (single-search)		streaming, citations
Thorough multi-search deep research
answers
 (research mode)		Iterative deep research, synthesized cited answer
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.
使用场景技能/接口原因
快速获取事实性回答（原始上下文）
llm-context
单次搜索，为你的LLM返回原始上下文
快速获取带引用的AI回答
answers
（单搜索模式）		支持流式响应、附带引用
全面的多轮深度研究
answers
（研究模式）		迭代式深度研究，生成带引用的综合回答
本接口 (
/res/v1/chat/completions
) 支持两种模式：
  • 单搜索（默认）：基于单次搜索快速生成AI事实性回答，支持
    enable_citations
    参数。
  • 研究模式（设置
    enable_research=true
    ）：多轮迭代深度研究，包含进度事件，生成带引用的综合回答。

Quick Start (cURL)

快速开始（cURL示例）

Blocking (Single-Search)

阻塞式响应（单搜索模式）

bash
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?"}],
    "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: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "How does the James Webb Space Telescope work?"}],
    "model": "brave",
    "stream": false
  }'

Streaming with Citations (Single-Search)

带引用的流式响应（单搜索模式）

bash
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?"}],
    "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: ${BRAVE_SEARCH_API_KEY}" \
  -d '{
    "messages": [{"role": "user", "content": "What are recent breakthroughs in fusion energy?"}],
    "model": "brave",
    "stream": true,
    "enable_citations": true
  }'

Research Mode

研究模式

bash
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"}],
    "model": "brave",
    "stream": true,
    "enable_research": true,
    "research_maximum_number_of_iterations": 3,
    "research_maximum_number_of_seconds": 120
  }'
bash
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"}],
    "model": "brave",
    "stream": true,
    "enable_research": true,
    "research_maximum_number_of_iterations": 3,
    "research_maximum_number_of_seconds": 120
  }'

Endpoint

接口信息

http
POST https://api.search.brave.com/res/v1/chat/completions
Authentication: 
X-Subscription-Token: <API_KEY>
header (or 
Authorization: Bearer <API_KEY>
)
SDK Compatible: Works with OpenAI SDK via 
base_url="https://api.search.brave.com/res/v1"
http
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

Two Modes

两种模式对比

FeatureSingle-Search (default)Research (
enable_research=true
)
SpeedFastSlow
Searches1Multiple (iterative)
StreamingOptional (
stream=true/false
)		Required (
stream=true
)
Citations
enable_citations=true
(streaming only)		Built-in (in 
<answer>
tag)
Progress eventsNoYes (
<progress>
tags)
Blocking responseYes (
stream=false
)		No
特性单搜索（默认）研究模式（
enable_research=true
）
响应速度快慢
搜索次数1次多次（迭代式）
流式响应可选（
stream=true/false
）		必填（
stream=true
）
引用来源需设置
enable_citations=true
（仅流式响应支持）		内置（包含在
<answer>
标签中）
进度事件无有（
<progress>
标签）
阻塞式响应支持（
stream=false
）		不支持

Parameters

参数说明

Standard Parameters

标准参数

ParameterTypeRequiredDefaultDescription
messages
arrayYes-Single user message (exactly 1 message)
model
stringYes-Use 
"brave"
stream
boolNotrueEnable SSE streaming
country
stringNo"US"Search country (2-letter country code or 
ALL
)
language
stringNo"en"Response language
safesearch
stringNo"moderate"Search safety level (
off
, 
moderate
, 
strict
)
max_completion_tokens
intNonullUpper bound on completion tokens
enable_citations
boolNofalseInclude inline citation tags (single-search streaming only)
web_search_options
objectNonullOpenAI-compatible; 
search_context_size
: 
low
, 
medium
, 
high
参数名类型是否必填默认值描述
messages
数组是-仅支持单条用户消息（数组中必须恰好包含1条消息）
model
字符串是-需设置为
"brave"
stream
布尔值否true启用SSE流式响应
country
字符串否"US"搜索地区（两位国家代码或
ALL
）
language
字符串否"en"响应语言
safesearch
字符串否"moderate"搜索安全级别（
off
、
moderate
、
strict
）
max_completion_tokens
整数否null生成内容的最大token数上限
enable_citations
布尔值否false启用内联引用标签（仅单搜索模式的流式响应支持）
web_search_options
对象否null兼容OpenAI的参数；
search_context_size
可选值：
low
、
medium
、
high

Research Parameters

研究模式专属参数

ParameterTypeRequiredDefaultDescription
enable_research
boolNo
false
Enable research mode
research_allow_thinking
boolNo
true
Enable extended thinking
research_maximum_number_of_tokens_per_query
intNo
8192
Max tokens per query (1024-16384)
research_maximum_number_of_queries
intNo
20
Max total search queries (1-50)
research_maximum_number_of_iterations
intNo
4
Max research iterations (1-5)
research_maximum_number_of_seconds
intNo
180
Time budget in seconds (1-300)
research_maximum_number_of_results_per_query
intNo
60
Results per search query (1-60)
参数名类型是否必填默认值描述
enable_research
布尔值否
false
启用研究模式
research_allow_thinking
布尔值否
true
启用扩展思考逻辑
research_maximum_number_of_tokens_per_query
整数否
8192
每个搜索查询的最大token数（范围1024-16384）
research_maximum_number_of_queries
整数否
20
最大总搜索查询次数（范围1-50）
research_maximum_number_of_iterations
整数否
4
最大研究迭代次数（范围1-5）
research_maximum_number_of_seconds
整数否
180
时间预算（秒，范围1-300）
research_maximum_number_of_results_per_query
整数否
60
每次搜索查询返回的结果数（范围1-60）

Constraints (IMPORTANT)

约束条件（重要）

ConstraintError
enable_research=true
requires 
stream=true
"Blocking response doesn't support 'enable_research' option"
enable_research=true
incompatible with 
enable_citations=true
"Research mode doesn't support 'enable_citations' option"
enable_citations=true
requires 
stream=true
"Blocking response doesn't support 'enable_citations' option"
约束条件错误提示
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 Usage

OpenAI SDK 使用示例

Blocking (Single-Search)

阻塞式响应（单搜索模式）

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": "How does the James Webb Space Telescope work?"}],
    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",
)

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)

Streaming with Citations (Single-Search)

带引用的流式响应（单搜索模式）

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": "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="")
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": "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="")

Research Mode

研究模式

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": "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)
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": "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)

Response Format

响应格式

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

阻塞式响应（
stream=false
，仅单搜索模式支持）

Standard OpenAI-compatible JSON:
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标准格式的JSON：
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}
}

Streaming Response

流式响应

SSE response with OpenAI-compatible chunks:
text
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]
采用SSE格式，返回兼容OpenAI的响应块：
text
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]

Streaming Tags by Mode

不同模式下的流式标签

Single-Search (with 
enable_citations=true
)

单搜索模式（启用
enable_citations=true
）

TagPurpose
<citation>
Inline citation references
<usage>
JSON cost/billing data
标签用途
<citation>
内联引用标记
<usage>
JSON格式的成本/计费数据

Research Mode

研究模式

TagPurposeKeep?
<queries>
Generated search queriesDebug
<analyzing>
URL counts (verbose)Debug
<thinking>
URL selection reasoningDebug
<progress>
Stats: time, iterations, queries, URLs analyzed, tokensMonitor
<blindspots>
Knowledge gaps identifiedYes
<answer>
Final synthesized answer (only the final answer is emitted; intermediate drafts are dropped)Yes
<usage>
JSON cost/billing data (included at end of streaming response)Yes
标签用途是否需要保留
<queries>
生成的搜索查询语句调试用
<analyzing>
待分析的URL数量（详细日志）调试用
<thinking>
URL选择的推理过程调试用
<progress>
统计信息：耗时、迭代次数、查询次数、已分析URL数、token数监控用
<blindspots>
识别出的知识盲区需要
<answer>
最终综合回答（仅输出最终结果；中间草稿会被丢弃）需要
<usage>
JSON格式的成本/计费数据（在流式响应末尾返回）需要

Usage Tag Format

Usage标签格式

The 
<usage>
tag contains JSON-stringified cost and token data:
text
<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>
<usage>
标签包含JSON序列化后的成本与token数据：
text
<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>

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.
  • 聊天界面集成：直接替换OpenAI SDK，生成基于网络事实的回答。只需设置
    base_url="https://api.search.brave.com/res/v1"
    即可。
  • 深度研究/主题调研：针对需要多源信息综合的复杂问题（如“对比核聚变的不同实现方案”），启用研究模式（
    enable_research=true
    ）。
  • OpenAI SDK无缝适配：使用相同的SDK与流式格式，仅需修改
    base_url
    和
    api_key
    。支持同步与异步客户端。
  • 带引用的回答：在单搜索模式下启用
    enable_citations=true
    获取内联引用标记，或使用研究模式（自动在回答中包含引用来源）。

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
  • 超时设置：单搜索模式建议将客户端超时设置为至少30秒，研究模式建议设置为300秒（5分钟）
  • 单条消息限制：
    messages
    数组必须恰好包含1条用户消息
  • 成本监控：通过解析流式响应中的
    <usage>
    标签跟踪使用成本