Web Search

Permettez à Claude de rechercher le web en temps réel lors de vos requêtes. Utile pour les dernières actualités, prix, versions, calendriers et faits survenus après la date de coupure du modèle.

Démarrage rapide

Ajoutez une entrée dans le tableau tools d'une requête /v1/messages. Le modèle décide s'il doit rechercher, quoi rechercher et combien de fois :

curl https://synthorai.io/v1/messages \
  -H "x-api-key: $YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "tools": [{"type": "synthorai:web_search"}],
    "messages": [
      {"role": "user", "content": "What is the latest Claude model?"}
    ]
  }'

ℹ

La recherche web n'est déclenchée que si vous incluez explicitement synthorai:web_search dans tools. Les requêtes sans cela sont des requêtes ordinaires, sans impact sur le comportement ni le coût.

Paramètres optionnels

Tous les champs de l'entrée synthorai:web_search sont optionnels :

Paramètre	Description
`max_uses`	Nombre maximum de cycles de recherche par requête (contrôle des coûts). Omettez pour utiliser la valeur par défaut de la plateforme.
`allowed_domains`	Recherche uniquement dans ces domaines (ex. `["arxiv.org","github.com"]`).
`blocked_domains`	Exclut ces domaines des résultats de recherche.

{
  "type": "synthorai:web_search",
  "max_uses": 3,
  "allowed_domains": ["anthropic.com", "openai.com"]
}

Structure de la réponse

Une réponse avec recherche inclut les types de blocs suivants dans content, dans cet ordre :

server_tool_use — la requête de recherche émise par le modèle.
web_search_tool_result — les résultats de recherche (titre, URL, extrait).
text — la réponse finale basée sur les résultats, avec citations des sources.

L'objet usage inclut un champ supplémentaire indiquant le nombre de recherches effectuées :

"usage": {
  "input_tokens": 14577,
  "output_tokens": 331,
  "server_tool_use": { "web_search_requests": 2 }
}

Facturation

Élément	Prix
Frais de recherche	$0.10 / recherche
Tokens des résultats de recherche	Prix d'entrée standard du modèle utilisé

La facturation comporte deux parties : $0,10 par recherche exécutée, plus le contenu web retourné facturé comme des tokens d'entrée (environ 7 000 à 14 000 tokens par recherche). Une requête avec recherche coûte nettement plus qu'une requête simple — utilisez max_uses pour limiter le nombre de recherches.

Trois façons de maîtriser les coûts :

Définir max_uses pour limiter le nombre de cycles de recherche.

Utiliser le cache de prompts (les résultats sont mis en cache avec cache_control — économies significatives dans les conversations multi-tours).

Utiliser allowed_domains pour restreindre le périmètre de recherche.

Benchmarks de référence (claude-sonnet-4-6, sans cache) :

Léger (2 recherches, vérification de fait) : ≈ $0,25 / requête

Intensif (8 recherches, recherche approfondie) : ≈ $1,05 / requête

Utilisation avec l'endpoint compatible OpenAI

Si vous utilisez /v1/chat/completions (format OpenAI), le comportement dépend du canal associé à votre clé : les canaux qui proxyfient vers OpenRouter utilisent la syntaxe de recherche de cet upstream (ex. tools:[{"type":"openrouter:web_search"}]) ; dans les autres cas, privilégiez /v1/messages + synthorai:web_search pour une meilleure compatibilité. Contactez-nous et nous confirmerons la bonne approche pour votre clé.

FAQ

J'utilise Claude Code / le SDK Anthropic — puis-je utiliser cette fonctionnalité ?

Oui — utilisez l'endpoint /v1/messages avec synthorai:web_search. Si votre clé est associée à un canal de relais en format OpenAI pur, l'outil de recherche natif peut ne pas fonctionner ; dans ce cas, nous configurerons un canal dédié pour vous.

Que se passe-t-il si une recherche échoue ?

Un cycle de recherche échoué n'est pas facturé. Le modèle reçoit le signal d'échec et tente soit une nouvelle requête, soit une réponse basée sur ses connaissances existantes. La requête globale ne génère pas d'erreur.

Le modèle peut-il faire des recherches sans que je le demande ?

Non. La recherche web n'est activée que lorsque vous incluez explicitement synthorai:web_search dans le tableau tools. Les requêtes ordinaires ne déclenchent jamais de recherche web.