Web Fetch

Dê ao modelo o texto completo de uma página cuja URL você já tem. Adicione uma entrada de ferramenta e a Synthorai obtém a página, limpa e coloca o corpo legível na conversa — em qualquer modelo, por qualquer canal.

Requisição mínima

Adicione synthorai:web_fetch em tools no /v1/messages. Nada mais muda:

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_fetch"}],
    "messages": [
      {"role": "user", "content": "Summarise https://docs.anthropic.com/en/docs/build-with-claude/tool-use"}
    ]
  }'

ℹ

Uma página só é obtida quando o modelo decide que precisa de uma e você incluiu synthorai:web_fetch. Requisições sem a ferramenta são requisições comuns — impacto zero em comportamento ou custo.

Opções

Todo campo da entrada synthorai:web_fetch é opcional:

Parâmetro	Descrição
`max_uses`	Máximo de páginas a obter em uma requisição. Padrão 3, teto 10. É um limite de gasto, então vale através de novas tentativas — uma requisição declarando `max_uses: 1` é cobrada por no máximo uma busca mesmo se repetida entre canais.

{
  "type": "synthorai:web_fetch",
  "max_uses": 2
}

Usando com Web Search

A busca encontra páginas; o fetch as lê. Declarar os dois deixa o modelo pesquisar, escolher um resultado promissor e puxar a página inteira — que costuma ser o que você quer em perguntas de pesquisa:

"tools": [
  {"type": "synthorai:web_search"},
  {"type": "synthorai:web_fetch"}
]

Formato da resposta

Cada busca aparece no turno do assistant como um par de blocos, seguido da resposta do modelo:

{
  "type": "server_tool_use",
  "id": "srvtoolu_synth_...",
  "name": "web_fetch",
  "input": { "url": "https://example.com/page" }
},
{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_synth_...",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/page",
    "title": "Example page",
    "content": { "type": "text", "text": "…page body…" }
  }
}

O número de buscas é reportado em usage, então você mesmo pode conciliar a cobrança:

"usage": {
  "input_tokens": 9241,
  "output_tokens": 412,
  "cache_read_input_tokens": 0,
  "cache_creation_input_tokens": 0,
  "server_tool_use": { "web_fetch_requests": 1 }
}

Cobrança

Item	Preço
Cada página obtida	$0.01 / busca
Tokens (prompt + conclusão)	Preço de entrada padrão do modelo utilizado

!
A taxa por busca não é o custo todo. Uma página obtida entra na conversa como tokens de entrada, e um artigo longo pode ser vários milhares deles — na maioria dos modelos esse custo em tokens excede a taxa de $0.01. Orce os dois.

Três formas de manter previsível:

Defina max_uses no menor número que sua tarefa precisa — ele limita a taxa da requisição inteira, incluindo novas tentativas.

Busque páginas específicas em vez de deixar o modelo explorar. Uma URL colada pelo usuário é uma busca; "ler ao redor do tema" podem ser três.

Observe usage.server_tool_use.web_fetch_requests e usage.input_tokens juntos — o dinheiro geralmente vai no segundo.

Limites e segurança

Apenas URLs http e https são obtidas. URLs com credenciais embutidas são rejeitadas.

Endereços privados, de loopback, link-local e de metadados de nuvem são recusados — o web_fetch alcança apenas páginas públicas.

Corpos de página são truncados a um limite de caracteres configurado antes de entrar na conversa, então uma única página enorme não pode inflar uma requisição sem limite.

Uma página que não pode ser obtida volta como bloco de erro em vez de falhar a requisição inteira, e o modelo pode reagir a isso ou responder sem a página.

Enquanto você declara synthorai:web_fetch, o nome puro web_fetch fica reservado — declarar uma ferramenta própria com esse nome retorna um 400 nomeando-a. Renomeie a sua, ou remova o parâmetro synthorai:.

Uma busca recusada antes de sair da nossa rede — URL rejeitada, domínio bloqueado, backend não configurado — não é cobrada. Uma que chegou ao provedor e falhou lá é cobrada, porque o provedor nos cobrou. Ambas contam em max_uses.

Sua responsabilidade pelo que você busca

O web_fetch obtém uma página por sua instrução. Você decide qual URL buscar, então essa recuperação e o que você faz com o que volta são responsabilidade sua.

Você precisa ter o direito de acessar o conteúdo. Isso inclui os termos de serviço do site alvo, seu robots.txt, qualquer paywall ou barreira de login, e os direitos autorais e de bases de dados aplicáveis. Buscar através de nós não concede acesso que você não teria de outra forma.

Dados pessoais continuam sendo obrigação sua. Se uma página obtida contém informações pessoais, você permanece o controlador delas sob GDPR, PIPL e regimes equivalentes — incluindo base legal, retenção e qualquer pedido de exclusão.

Reivindicações decorrentes das suas buscas são suas. Se um detentor de direitos ou operador de site apresentar uma reivindicação sobre conteúdo que você obteve, ela é dirigida a você e o custo é seu. Isso espelha os termos dos provedores de recuperação upstream pelos quais roteamos.

A saída do modelo não está liberada para reuso. Uma resposta construída sobre material obtido pode reproduzir partes dele. Se você pode republicar essa saída é uma questão da licença da fonte, e não fazemos nenhuma declaração a respeito.

O que é conosco: operamos a infraestrutura de recuperação, bloqueamos endereços internos e de rede privada, honramos a lista de bloqueio de domínios que seu administrador configura e não retemos conteúdo de páginas além de servir sua requisição. Não revisamos a legalidade de URLs individuais, e não podemos — uma URL sozinha não carrega sua licença.

!
Suspenderemos o web_fetch de uma chave de API que atraia denúncias críveis de abuso ou que um provedor de recuperação sinalize, porque uma conta de provedor suspensa derruba o recurso para todos os clientes.

FAQ

O modelo pode obter uma página que eu não mencionei?

Ele pode seguir uma URL que encontrou via synthorai:web_search na mesma conversa, que é o propósito de combinar os dois. Ele é instruído a não inventar URLs; se precisar achar uma página, deve pesquisar primeiro.

O que acontece se a página estiver atrás de login ou bloquear rastreadores?

Você recebe um bloco de erro para aquela busca e o modelo continua sem a página. A busca ainda conta em max_uses porque a requisição foi realmente feita em seu nome.

Declarar a ferramenta muda algo quando nenhuma página é obtida?

Não. Cobrança e comportamento são idênticos a uma requisição comum até o modelo realmente obter algo.