Answers — AI Grounding

Requiert une clé API : Obtenez-en une sur https://api.search.brave.com

Plan : Inclus dans le plan Answers. Voir https://api-dashboard.search.brave.com/app/subscriptions/subscribe

Quand utiliser

Cet endpoint (/res/v1/chat/completions) supporte deux modes :

• Recherche unique (par défaut) : Réponse IA rapide ancrée dans une seule recherche. Supporte enable_citations.
• Recherche (enable_research=true) : Recherche approfondie multi-itération avec événements de progression et réponse citée synthétisée.

Démarrage rapide (cURL)

Bloquant (Recherche unique)

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 avec citations (Recherche unique)

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
  }'

Mode recherche

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

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

Authentification : En-tête X-Subscription-Token: <API_KEY> (ou Authorization: Bearer <API_KEY>)

Compatible SDK : Fonctionne avec le SDK OpenAI via base_url="https://api.search.brave.com/res/v1"

Deux modes

Paramètres

Paramètres standards

Paramètres de recherche

Contraintes (IMPORTANT)

Utilisation du SDK OpenAI

Bloquant (Recherche unique)

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 avec citations (Recherche unique)

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

Mode recherche

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)

Format de réponse

Réponse bloquante (stream=false, recherche unique uniquement)

JSON compatible OpenAI standard :

{
  "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}
}

Réponse streaming

Réponse SSE avec chunks compatibles OpenAI :

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]

Balises de streaming par mode

Recherche unique (avec enable_citations=true)

Mode recherche

Format de la balise d'utilisation

La balise <usage> contient des données de coût et de tokens en JSON stringifié :

<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>

Cas d'usage

• Intégration d'interface de chat : Remplacement SDK OpenAI clé en main avec réponses ancrées dans le web. Définissez base_url="https://api.search.brave.com/res/v1".
• Recherche approfondie / recherche thématique exhaustive : Utilisez le mode recherche (enable_research=true) pour les questions complexes nécessitant une synthèse multi-source (par exemple, « Compare approaches to nuclear fusion »).
• SDK OpenAI clé en main : Même SDK, même format streaming — changez simplement base_url et api_key. Fonctionne avec les clients sync et async.
• Réponses citées : Activez enable_citations=true en mode recherche unique pour les balises de citation intégrées, ou utilisez le mode recherche qui inclut automatiquement les citations dans sa réponse.

Notes

• Timeout : Définissez le délai d'expiration du client à au moins 30 s pour recherche unique, 300 s (5 min) pour recherche
• Message unique : Le tableau messages doit contenir exactement 1 message utilisateur
• Surveillance des coûts : Analysez la balise <usage> des réponses streaming pour suivre les coûts