Web Search

Consente a Claude di cercare sul web in tempo reale mentre risponde alle richieste. Utile per ultime notizie, prezzi, versioni, calendari e fatti avvenuti dopo il cutoff del modello.

Avvio rapido

Aggiungi una voce all'array tools di una richiesta /v1/messages. Il modello decide autonomamente se cercare, cosa cercare e quante volte:

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 ricerca web viene attivata solo quando includi esplicitamente synthorai:web_search in tools. Le richieste senza di essa sono richieste ordinarie — nessun impatto su comportamento o costi.

Parametri opzionali

Tutti i campi della voce synthorai:web_search sono opzionali:

Parametro	Descrizione
`max_uses`	Numero massimo di cicli di ricerca per richiesta (controllo dei costi). Ometti per usare il valore predefinito della piattaforma.
`allowed_domains`	Cerca solo in questi domini (es. `["arxiv.org","github.com"]`).
`blocked_domains`	Escludi questi domini dai risultati di ricerca.

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

Struttura della risposta

Una risposta con ricerca include i seguenti tipi di blocco in content, in ordine:

server_tool_use — la query di ricerca emessa dal modello.
web_search_tool_result — i risultati di ricerca (titolo, URL, snippet).
text — la risposta finale basata sui risultati, con citazioni delle fonti.

L'oggetto usage include un campo aggiuntivo che indica quante ricerche sono state eseguite:

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

Fatturazione

Voce	Prezzo
Tariffa di ricerca	$0.10 / ricerca
Token dei risultati di ricerca	Prezzo input standard del modello utilizzato

La fatturazione ha due parti: $0,10 per ogni ricerca eseguita, più il contenuto web restituito fatturato come token di input (circa 7.000–14.000 token per ricerca). Una richiesta con ricerca costa sensibilmente più di una semplice — usa max_uses per limitare il numero di ricerche.

Tre modi per controllare i costi:

Impostare max_uses per limitare il numero di cicli di ricerca.

Usare il prompt caching (i risultati vengono messi in cache con cache_control — risparmio significativo nelle conversazioni multi-turno).

Usare allowed_domains per restringere l'ambito di ricerca.

Benchmark di riferimento (claude-sonnet-4-6, senza cache):

Leggero (2 ricerche, verifica fatti): ≈ $0,25 / richiesta

Intenso (8 ricerche, ricerca approfondita): ≈ $1,05 / richiesta

Utilizzo con l'endpoint compatibile OpenAI

Se utilizzi /v1/chat/completions (formato OpenAI), il comportamento dipende dal canale associato alla chiave: i canali che inoltrano a OpenRouter usano la sintassi dello strumento di ricerca di quell'upstream (es. tools:[{"type":"openrouter:web_search"}]); negli altri casi, si raccomanda /v1/messages + synthorai:web_search per la massima compatibilità. Contattaci e confermeremo l'approccio giusto per la tua chiave.

Domande frequenti

Uso Claude Code / l'SDK Anthropic — posso usarlo?

Sì — usa l'endpoint /v1/messages con synthorai:web_search. Se la tua chiave è associata a un canale di relay in puro formato OpenAI, lo strumento di ricerca nativo potrebbe non funzionare; in tal caso configureremo un canale dedicato per te.

Cosa succede se una ricerca fallisce?

Un ciclo di ricerca fallito non viene fatturato. Il modello riceve il segnale di errore e tenta una query diversa oppure risponde basandosi sulla conoscenza esistente. La richiesta complessiva non genera un errore.

Il modello può cercare senza che io lo richieda?

No. La ricerca web viene attivata solo quando includi esplicitamente synthorai:web_search nell'array tools. Le richieste ordinarie non attivano mai una ricerca web.