Web Search

Permite que o Claude pesquise na web em tempo real ao responder às suas solicitações. Útil para notícias recentes, preços, versões, agendas e fatos ocorridos após o corte de treinamento.

Início rápido

Adicione uma entrada ao array tools de uma solicitação /v1/messages. O modelo decide se deve pesquisar, o quê pesquisar e quantas vezes:

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?"}
    ]
  }'

ℹ

A pesquisa web só é acionada quando você inclui explicitamente synthorai:web_search em tools. Solicitações sem isso são solicitações comuns — sem impacto no comportamento nem no custo.

Parâmetros opcionais

Todos os campos da entrada synthorai:web_search são opcionais:

Parâmetro	Descrição
`max_uses`	Número máximo de rodadas de pesquisa por solicitação (controle de custos). Omita para usar o padrão da plataforma.
`allowed_domains`	Pesquisa apenas nesses domínios (ex.: `["arxiv.org","github.com"]`).
`blocked_domains`	Exclui esses domínios dos resultados de pesquisa.

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

Estrutura da resposta

Uma resposta com pesquisa inclui os seguintes tipos de bloco em content, em ordem:

server_tool_use — a consulta de pesquisa emitida pelo modelo.
web_search_tool_result — os resultados de pesquisa (título, URL, trecho).
text — a resposta final baseada nos resultados, com citações de fontes.

O objeto usage inclui um campo adicional informando quantas pesquisas foram executadas:

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

Cobrança

Item	Preço
Taxa de pesquisa	$0.10 / pesquisa
Tokens dos resultados de pesquisa	Preço de entrada padrão do modelo utilizado

A cobrança tem duas partes: $0,10 por pesquisa executada, mais o conteúdo web retornado cobrado como tokens de entrada (cerca de 7.000–14.000 tokens por pesquisa). Uma solicitação com pesquisa custa consideravelmente mais que uma simples — use max_uses para limitar o número de pesquisas.

Três formas de controlar os custos:

Definir max_uses para limitar o número de rodadas de pesquisa.

Usar o cache de prompts (os resultados são armazenados em cache com cache_control — economia significativa em conversas de múltiplos turnos).

Usar allowed_domains para restringir o escopo da pesquisa.

Referências de benchmark (claude-sonnet-4-6, sem cache):

Leve (2 pesquisas, verificação de fatos): ≈ $0,25 / solicitação

Intenso (8 pesquisas, pesquisa aprofundada): ≈ $1,05 / solicitação

Uso com o endpoint compatível com OpenAI

Se você usa /v1/chat/completions (formato OpenAI), o comportamento depende do canal vinculado à sua chave: canais que fazem proxy para o OpenRouter usam a sintaxe de ferramenta de pesquisa do upstream (ex.: tools:[{"type":"openrouter:web_search"}]); nos demais casos, prefira /v1/messages + synthorai:web_search para melhor compatibilidade. Entre em contato conosco e confirmaremos a abordagem certa para sua chave.

Perguntas frequentes

Uso o Claude Code / o SDK da Anthropic — posso usar isso?

Sim — use o endpoint /v1/messages com synthorai:web_search. Se sua chave estiver vinculada a um canal de retransmissão em formato OpenAI puro, a ferramenta de pesquisa nativa pode não funcionar; nesse caso, configuraremos um canal dedicado para você.

O que acontece se uma pesquisa falhar?

Uma rodada de pesquisa com falha não é cobrada. O modelo recebe o sinal de falha e tenta uma consulta diferente ou responde com base no conhecimento existente. A solicitação geral não retorna erro.

O modelo pode pesquisar sem que eu solicite?

Não. A pesquisa web só é ativada quando você inclui explicitamente synthorai:web_search no array tools. Solicitações comuns nunca acionam uma pesquisa web.