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.01 / recherche
Tokens des résultats de recherche	Prix d'entrée standard du modèle utilisé

La facturation comporte deux parties : $0,01 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,07 / requête

Intensif (8 recherches, recherche approfondie) : ≈ $0,33 / requête

Utilisation avec l'endpoint compatible OpenAI

synthorai:web_search fonctionne aussi sur /v1/chat/completions et /v1/responses - déclarez la même entrée que pour /v1/messages. Ce que renvoie chaque endpoint : sur les deux endpoints compatibles OpenAI, les sources récupérées reviennent sous forme d'annotations OpenAI (forme url_citation) - sur le message pour chat completions, sur l'élément output_text pour responses ; sur /v1/messages, la même recherche revient sous forme de blocs server_tool_use et web_search_tool_result. Sur tous les endpoints, le champ usage couvre tous les tours de la recherche : les tokens facturés sont ceux que vous voyez. Les canaux qui passent par OpenRouter peuvent utiliser la syntaxe d'outil de recherche de cet upstream (p. ex. tools:[{"type":"openrouter:web_search"}]). Le paramètre synthorai: est accepté sur /v1/messages, /v1/chat/completions et /v1/responses - envoyé à un endpoint Gemini, il renvoie un 400 qui l'explique, plutôt que de transmettre en amont un outil que votre modèle ne reconnaît pas. Contactez-nous et nous confirmerons l'approche adaptée à votre clé.

Nom d'outil réservé

Tant que vous déclarez synthorai:web_search, le nom nu web_search est réservé : déclarer votre propre outil sous ce nom renvoie un 400 le nommant. Renommez votre outil ou retirez le paramètre synthorai:. Nous injectons l'outil de recherche sous ce nom exact ; deux outils homonymes atteindraient le modèle et aucune des deux parties ne saurait à qui appartient l'appel renvoyé. Utiliser ce nom pour votre propre outil sans le paramètre synthorai: n'est pas concerné - nous n'injectons rien, donc rien n'entre en collision.

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.