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.01 / pesquisa
Tokens dos resultados de pesquisa	Preço de entrada padrão do modelo utilizado

A cobrança tem duas partes: $0,01 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,07 / solicitação

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

Uso com o endpoint compatível com OpenAI

synthorai:web_search também funciona em /v1/chat/completions e /v1/responses - declare a mesma entrada que enviaria para /v1/messages. O que cada endpoint devolve: nos dois endpoints compatíveis com OpenAI, as fontes recuperadas voltam como annotations da OpenAI (formato url_citation) - na mensagem para chat completions, no item output_text para responses; em /v1/messages, a mesma busca volta como blocos server_tool_use e web_search_tool_result. Em todos os endpoints, o usage informado cobre todas as rodadas da busca: os tokens cobrados são os que você vê. Canais que fazem proxy para o OpenRouter podem usar a sintaxe de ferramenta de busca desse upstream (ex.: tools:[{"type":"openrouter:web_search"}]). O parâmetro synthorai: é aceito em /v1/messages, /v1/chat/completions e /v1/responses - enviá-lo a um endpoint Gemini devolve um 400 explicando isso, em vez de repassar ao upstream uma ferramenta que seu modelo não reconhece. Fale conosco e confirmaremos a abordagem certa para a sua chave.

Nome de ferramenta reservado

Enquanto você declara synthorai:web_search, o nome puro web_search fica reservado: declarar uma ferramenta sua com esse nome retorna um 400 indicando o nome. Renomeie sua ferramenta ou remova o parâmetro synthorai:. Injetamos a ferramenta de busca exatamente com esse nome, então duas ferramentas homônimas chegariam ao modelo e nenhum dos lados saberia de quem é a chamada retornada. Usar o nome para sua própria ferramenta sem o parâmetro synthorai: não é afetado - não injetamos nada, então nada colide.

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.