Web Search

Permite que Claude busque en la web en tiempo real al responder tus solicitudes. Útil para noticias recientes, precios, versiones, calendarios y hechos posteriores al corte de entrenamiento.

Inicio rápido

Añade una entrada al array tools de una solicitud /v1/messages. El modelo decide si buscar, qué buscar y cuántas veces:

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 búsqueda web solo se activa cuando incluyes explícitamente synthorai:web_search en tools. Las solicitudes sin esto son solicitudes ordinarias: sin impacto en el comportamiento ni en el coste.

Parámetros opcionales

Todos los campos de la entrada synthorai:web_search son opcionales:

Parámetro	Descripción
`max_uses`	Número máximo de rondas de búsqueda por solicitud (control de costes). Omitir para usar el valor predeterminado de la plataforma.
`allowed_domains`	Busca solo dentro de estos dominios (p. ej. `["arxiv.org","github.com"]`).
`blocked_domains`	Excluye estos dominios de los resultados de búsqueda.

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

Estructura de la respuesta

Una respuesta con búsqueda incluye los siguientes tipos de bloque en content, en orden:

server_tool_use — la consulta de búsqueda emitida por el modelo.
web_search_tool_result — los resultados de búsqueda (título, URL, fragmento).
text — la respuesta final basada en los resultados, con citas de fuentes.

El objeto usage incluye un campo adicional que indica cuántas búsquedas se ejecutaron:

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

Facturación

Elemento	Precio
Tarifa de búsqueda	$0.10 / búsqueda
Tokens de resultados de búsqueda	Precio de entrada estándar del modelo utilizado

La facturación tiene dos partes: $0,10 por búsqueda ejecutada, más el contenido web devuelto facturado como tokens de entrada (aproximadamente 7.000–14.000 tokens por búsqueda). Una solicitud con búsqueda cuesta notablemente más que una simple — usa max_uses para limitar el número de búsquedas.

Tres formas de controlar el coste:

Establecer max_uses para limitar el número de rondas de búsqueda.

Usar el caché de prompts (los resultados se almacenan en caché con cache_control — ahorro significativo en conversaciones de varios turnos).

Usar allowed_domains para acotar el ámbito de búsqueda.

Referencia de benchmarks (claude-sonnet-4-6, sin caché):

Ligero (2 búsquedas, verificación de hechos): ≈ $0,25 / solicitud

Intenso (8 búsquedas, investigación): ≈ $1,05 / solicitud

Uso con el endpoint compatible con OpenAI

Si usas /v1/chat/completions (formato OpenAI), el comportamiento depende del canal vinculado a tu clave: los canales que enrutan a OpenRouter usan la sintaxis de herramienta de búsqueda de ese upstream (p. ej. tools:[{"type":"openrouter:web_search"}]); en todos los demás casos, se recomienda /v1/messages + synthorai:web_search para mayor compatibilidad. Contáctanos y confirmaremos el enfoque adecuado para tu clave.

Preguntas frecuentes

Uso Claude Code / el SDK de Anthropic — ¿puedo usar esto?

Sí — usa el endpoint /v1/messages con synthorai:web_search. Si tu clave está vinculada a un canal de retransmisión de formato OpenAI puro, la herramienta de búsqueda nativa puede no funcionar; en ese caso, configuraremos un canal dedicado para ti.

¿Qué ocurre si una búsqueda falla?

Una ronda de búsqueda fallida no se factura. El modelo recibe la señal de fallo e intenta una consulta diferente o responde basándose en su conocimiento existente. La solicitud general no genera un error.

¿Puede el modelo buscar sin que yo lo solicite?

No. La búsqueda web solo se activa cuando incluyes explícitamente synthorai:web_search en el array tools. Las solicitudes ordinarias nunca activan una búsqueda web.