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.01 / ricerca
Token dei risultati di ricerca	Prezzo input standard del modello utilizzato

La fatturazione ha due parti: $0,01 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,07 / richiesta

Intenso (8 ricerche, ricerca approfondita): ≈ $0,33 / richiesta

Utilizzo con l'endpoint compatibile OpenAI

synthorai:web_search funziona anche su /v1/chat/completions e /v1/responses: dichiarate la stessa voce che invereste a /v1/messages. Cosa restituisce ciascun endpoint: sui due endpoint compatibili con OpenAI le fonti recuperate tornano come annotations di OpenAI (forma url_citation) - sul messaggio per chat completions, sull'elemento output_text per responses; su /v1/messages la stessa ricerca torna come blocchi server_tool_use e web_search_tool_result. Su tutti gli endpoint lo usage riportato copre tutti i round della ricerca: i token fatturati sono quelli che vedete. I canali che fanno da proxy verso OpenRouter possono usare la sintassi dello strumento di ricerca di quell'upstream (es. tools:[{"type":"openrouter:web_search"}]). Il parametro synthorai: è accettato su /v1/messages, /v1/chat/completions e /v1/responses: inviarlo a un endpoint Gemini restituisce un 400 che lo spiega, invece di inoltrare a monte uno strumento che il vostro modello non riconosce. Contattateci e confermeremo l'approccio giusto per la vostra chiave.

Nome dello strumento riservato

Finché dichiari synthorai:web_search, il nome semplice web_search è riservato: dichiarare un tuo strumento con quel nome restituisce un 400 che lo indica. Rinomina il tuo strumento oppure rimuovi il parametro synthorai:. Iniettiamo lo strumento di ricerca esattamente con quel nome, quindi due strumenti omonimi raggiungerebbero il modello e nessuna delle parti saprebbe a chi appartiene la chiamata restituita. Usare quel nome per un tuo strumento senza il parametro synthorai: non è interessato - non iniettiamo nulla, quindi nulla collide.

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.