Web Search

Ermöglicht Claude, bei der Beantwortung von Anfragen in Echtzeit im Web zu suchen. Nützlich für aktuelle Nachrichten, Preise, Versionen, Zeitpläne und Fakten nach dem Trainings-Cutoff.

Schnellstart

Fügen Sie einen Eintrag zum tools-Array einer /v1/messages-Anfrage hinzu. Das Modell entscheidet selbst, ob, was und wie oft es sucht:

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

ℹ

Web-Suche wird nur ausgelöst, wenn Sie synthorai:web_search explizit in tools aufnehmen. Anfragen ohne diesen Eintrag sind normale Anfragen - kein Einfluss auf Verhalten oder Kosten.

Optionale Parameter

Alle Felder des synthorai:web_search-Eintrags sind optional:

Parameter	Beschreibung
`max_uses`	Maximale Anzahl von Suchrunden pro Anfrage (Kostenkontrolle). Auslassen für Plattform-Standard.
`allowed_domains`	Suche nur innerhalb dieser Domains (z. B. `["arxiv.org","github.com"]`).
`blocked_domains`	Diese Domains aus den Suchergebnissen ausschließen.

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

Antwortstruktur

Eine Antwort mit Suche enthält folgende Blocktypen in content, in dieser Reihenfolge:

server_tool_use - die vom Modell ausgeführte Suchanfrage.
web_search_tool_result - die Suchergebnisse (Titel, URL, Snippet).
text - die endgültige Antwort auf Basis der Ergebnisse, mit Quellenangaben.

Das usage-Objekt enthält ein zusätzliches Feld mit der Anzahl der ausgeführten Suchen:

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

Abrechnung

Posten	Preis
Suchgebühr	$0.01 / Suche
Suchergebnis-Token	Standard-Input-Preis des verwendeten Modells

Die Abrechnung besteht aus zwei Teilen: $0,01 pro ausgeführter Suche, plus der zurückgegebene Webinhalt, der als Input-Token abgerechnet wird (etwa 7.000-14.000 Token pro Suche). Eine Anfrage mit Suche kostet spürbar mehr als eine einfache - nutzen Sie max_uses, um die Anzahl der Suchen zu begrenzen.

Drei Wege zur Kostenkontrolle:

max_uses setzen, um die Anzahl der Suchrunden zu begrenzen.

Prompt-Caching nutzen (Ergebnisse werden bei cache_control gecacht - erhebliche Einsparungen in Multi-Turn-Gesprächen).

allowed_domains verwenden, um den Suchbereich einzuschränken.

Referenz-Benchmarks (claude-sonnet-4-6, ohne Cache):

Leicht (2 Suchen, Faktencheck): ≈ $0,07 / Anfrage

Intensiv (8 Suchen, Recherche): ≈ $0,33 / Anfrage

Verwendung mit dem OpenAI-kompatiblen Endpunkt

synthorai:web_search funktioniert auch auf /v1/chat/completions und /v1/responses - deklarieren Sie denselben Eintrag wie für /v1/messages. Was jeder Endpunkt zurückgibt: Auf den beiden OpenAI-kompatiblen Endpunkten kommen die gefundenen Quellen als OpenAI-annotations (url_citation-Form) zurück - bei Chat Completions an der Nachricht, bei Responses am output_text-Element; auf /v1/messages liefert dieselbe Suche server_tool_use- und web_search_tool_result-Blöcke. Auf allen Endpunkten umfasst das gemeldete usage sämtliche Runden der Suche - die abgerechneten Tokens sind genau die sichtbaren. Kanäle, die zu OpenRouter proxen, können stattdessen die Suchwerkzeug-Syntax des Upstreams verwenden (z. B. tools:[{"type":"openrouter:web_search"}]). Der Parameter synthorai: wird auf /v1/messages, /v1/chat/completions und /v1/responses akzeptiert - an einen Gemini-Endpunkt gesendet, gibt er einen erklärenden 400 zurück, statt ein Werkzeug weiterzureichen, das Ihr Modell nicht kennt. Kontaktieren Sie uns, und wir bestätigen den richtigen Ansatz für Ihren Schlüssel.

Reservierter Toolname

Solange Sie synthorai:web_search deklarieren, ist der nackte Name web_search reserviert: Deklarieren Sie ein eigenes Tool unter diesem Namen, erhalten Sie einen 400, der den Namen nennt. Benennen Sie Ihr Tool um oder entfernen Sie den Parameter synthorai:. Wir injizieren das Suchtool unter genau diesem Namen - zwei gleichnamige Tools würden das Modell erreichen und keine Seite könnte zuordnen, wessen Aufruf zurückkam. Den Namen ohne den Parameter synthorai: für ein eigenes Tool zu verwenden ist unproblematisch - wir injizieren nichts, also kollidiert nichts.

FAQ

Ich verwende Claude Code / das Anthropic SDK - kann ich das nutzen?

Ja - verwenden Sie den Endpunkt /v1/messages mit synthorai:web_search. Wenn Ihr Schlüssel an einen reinen OpenAI-Format-Relay-Kanal gebunden ist, funktioniert das native Suchwerkzeug möglicherweise nicht; in diesem Fall konfigurieren wir einen dedizierten Kanal für Sie.

Was passiert, wenn eine Suche fehlschlägt?

Eine fehlgeschlagene Suchrunde wird nicht berechnet. Das Modell erhält das Fehlersignal und versucht entweder eine andere Anfrage oder antwortet auf Basis seines Trainings-Wissens. Die gesamte Anfrage schlägt nicht fehl.

Kann das Modell ohne meine Anfrage suchen?

Nein. Web-Suche wird nur aktiviert, wenn Sie synthorai:web_search explizit im tools-Array aufnehmen. Normale Anfragen lösen nie eine Web-Suche aus.