answers

Answers — AI グラウンディング

API キーが必要です：https://api.search.brave.com で取得してください。

プラン：Answers プランに含まれています。https://api-dashboard.search.brave.com/app/subscriptions/subscribe をご覧ください。

使用する場面

ユースケース	スキル	理由
手早く事実を確認する回答（生のコンテキスト）	llm-context	1 回の検索で、ユーザーの LLM 向けに生のコンテキストを返します
引用付きの高速な AI 回答	answers（単一検索）	ストリーミング、引用
複数回検索による徹底的な詳細調査	answers（リサーチモード）	反復的な詳細調査、引用付きの回答を統合

このエンドポイント（/res/v1/chat/completions）は、次の 2 つのモードに対応しています。

• 単一検索（デフォルト）：1 回の検索に基づく、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 で動作します。

2 つのモード

機能	単一検索（デフォルト）	リサーチ（enable_research=true）
速度	高速	低速
検索回数	1 回	複数回（反復）
ストリーミング	任意（stream=true/false）	必須（stream=true）
引用	enable_citations=true（ストリーミング時のみ）	組み込み（<answer> タグ内）
進捗イベント	なし	あり（<progress> タグ）
ブロッキング応答	あり（stream=false）	なし

パラメーター

標準パラメーター

パラメーター	型	必須	デフォルト	説明
messages	array	はい	-	ユーザーメッセージ 1 件（メッセージは正確に 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 の場合）

タグ	目的
<citation>	インラインの引用参照
<usage>	JSON 形式のコスト／課金データ

リサーチモード

タグ	目的	保持する？
<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 を有効にするとインライン引用タグが付きます。または、回答に引用が自動的に含まれるリサーチモードを使用します。

注意事項

• タイムアウト：単一検索ではクライアントのタイムアウトを 30 秒以上、リサーチでは 300 秒（5 分）に設定します。
• 単一メッセージ：messages 配列には、ユーザーメッセージを 1 つだけ含める必要があります。
• コストの監視：ストリーミングレスポンスから <usage> タグを解析して、コストを追跡します。