Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Websuche

Ermögliche Modellen, vor dem Antworten im Web nach aktuellen Informationen zu suchen.

Mit der Websuche können Modelle aktuelle Informationen aus dem Internet abrufen und ihre Antworten mit Quellen belegen. Verwende dazu das Tool für die Websuche in der Responses API oder, in bestimmten Fällen, in Chat Completions.

Wähle das Suchverfahren passend zu der Frage, die du beantworten möchtest.

  • Wenn du schnell etwas nachschlagen möchtest, bitte ein Modell, gezielt nach der Information zu suchen und die Quelle anzugeben.
  • Wenn du für eine Frage mehrere Quellen brauchst, verwende ein Reasoning-Modell wie gpt-6-astra. Es kann seine Suchanfragen anhand der bisherigen Ergebnisse verfeinern. Verwende den Hintergrundmodus, wenn die Bearbeitung einer Anfrage mehrere Minuten dauern könnte.

Integration auswählen

Anwendungsfall Empfehlung Hinweise
Neue Integration der Websuche Responses API mit web_search und gpt-6-astra Unterstützt Filter, Quellenlisten, die Steuerung des Livezugriffs und längere Recherchen mit der gehosteten Websuche
Bestehende Suchintegration mit Chat Completions Chat Completions mit gpt-5-search-api Verwende diese Variante nur, wenn du eine Integration mit Chat Completions beibehalten musst
Mehrstufige Recherche oder zeitaufwendige Berichte gpt-6-astra mit einem Reasoning-Aufwand von high oder xhigh Verwende den Hintergrundmodus für Berichte, deren Erstellung mehrere Minuten dauern kann

In der Responses API aktivierst du die Websuche, indem du sie im tools-Array der API-Anfrage zur Inhaltserstellung konfigurierst. Wie bei anderen Tools entscheidet das Modell anhand des Prompts, ob es das Web durchsucht.

Verwende für neue Integrationen mit der Responses API { "type": "web_search" }. Das ältere Tool web_search_preview ist für bestehende Integrationen weiterhin verfügbar. Es unterstützt jedoch keine neueren Parameter wie filters, external_web_access und return_token_budget.

Beispiel für das Tool zur Websuche
import OpenAI from "openai";
const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-6-astra",
  tools: [{ type: "web_search" }],
  input: "What was a positive news story from today?",
});

console.log(response.output_text);

Ausgabe und Quellenverweise

Wenn das Modell das Tool für die Websuche verwendet, enthält seine Antwort zwei Teile:

  • Ein Ausgabeelement vom Typ web_search_call mit der ID des Suchaufrufs. In web_search_call.action steht, welche Aktion ausgeführt wurde. Folgende Aktionen sind möglich:
    • search steht für eine Websuche. Die Aktion enthält in der Regel, aber nicht immer, die verwendeten Suchanfragen in queries. Für Suchaktionen fallen Kosten pro Toolaufruf an (siehe Preise).
    • open_page steht für das Öffnen einer Seite. Reasoning-Modelle unterstützen diese Aktion.
    • find_in_page steht für die Suche innerhalb einer Seite. Reasoning-Modelle unterstützen diese Aktion.
  • Ein Ausgabeelement vom Typ message mit folgenden Inhalten:
    • Der Antworttext in message.content[0].text
    • Die Annotationen in message.content[0].annotations für die zitierten URLs

Standardmäßig verweist das Modell direkt im Antworttext auf URLs aus den Suchergebnissen. Das Annotationsobjekt url_citation enthält außerdem die URL und den Titel der Quelle sowie die Position des Verweises im Text.

Wenn deine Benutzeroberfläche Suchergebnisse aus dem Web oder Informationen daraus anzeigt, musst du die Quellenverweise direkt im Text als deutlich sichtbare, anklickbare Links darstellen.

[
  {
    "type": "web_search_call",
    "id": "ws_67c9fa0502748190b7dd390736892e100be649c1a5ff9609",
    "status": "completed",
    "action": {
      "type": "search",
      "query": "latest news about AI"
    }
  },
  {
    "id": "msg_67c9fa077e288190af08fdffda2e34f20be649c1a5ff9609",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "On March 6, 2025, several news...",
        "annotations": [
          {
            "type": "url_citation",
            "start_index": 2606,
            "end_index": 2758,
            "url": "https://...",
            "title": "Title..."
          }
        ]
      }
    ]
  }
]

Von älteren Varianten der Websuche migrieren

Bisherige Integration Empfehlung Hinweise
web_search_preview in der Responses API Wechsle zu web_search web_search unterstützt neuere Parameter wie filters, external_web_access und return_token_budget
gpt-4o-search-preview oder gpt-4o-mini-search-preview Wechsle zu web_search in der Responses API oder verwende gpt-5-search-api, wenn du bei Chat Completions bleiben musst Die Vorschaumodelle für die Suche sind veraltet und wurden am 23. Juli 2026 abgeschaltet
Suchintegrationen mit Chat Completions Verwende gpt-5-search-api oder wechsle zu web_search in der Responses API, wenn du mehr Einstellungen für das Tool brauchst oder die Suche optional sein soll Die Suchmodelle in Chat Completions führen vor jeder Antwort eine Suche aus. In der Responses API steht die Suche als Tool zur Verfügung
o4-mini in der Responses API Wechsle zu einem unterstützten Reasoning-Modell mit web_search Das Modell wurde am 23. Oktober 2026 abgeschaltet

Wenn deine Integration noch gpt-5 verwendet, musst du für die Websuche einen höheren Reasoning-Aufwand als minimal einstellen.

Größe des Suchkontexts

Mit search_context_size legst du fest, wie viel Kontext aus den Suchergebnissen dem Modell zur Verfügung steht, bevor es antwortet. Verwende low, wenn du nur wenige Details nachschlagen möchtest, medium als ausgewogenen Standardwert und high, wenn die Antwort mehr Details aus den Suchergebnissen erfordern könnte. Diese Einstellung legt keine genaue Anzahl von Token fest und garantiert keine bestimmte Anzahl von Quellen oder Quellenverweisen.

Größe des Suchkontexts festlegen
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "web_search",
      search_context_size: "low",
    },
  ],
  input: "What movie won best picture in 2025?",
});
console.log(response.output_text);

Längere Webrecherchen durchführen

Wenn du für deine Recherche auch private Daten heranziehst, führe die öffentliche Websuche und die Abfrage privater Daten über MCP in getrennten Anfragen aus.

Mit return_token_budget legst du fest, wie viel Inhalt aus den Suchergebnissen das Tool bei einer Websuche mit Reasoning-Modellen ab GPT-5 über die Responses API zurückgeben kann. Behalte für die meisten Anfragen den Standardwert bei. Setze den Parameter nur dann auf unlimited, wenn für eine aufwendige Recherche oder Evaluation viele Seiten ausgewertet werden müssen und die Suche sonst beim Erreichen des üblichen Token-Limits für zurückgegebene Ergebnisse abbrechen könnte.

Verwende unlimited gezielt, da die Suche länger dauern und höhere Kosten verursachen kann. Nutze für längere Aufgaben mit mehreren Suchvorgängen den Hintergrundmodus (background: true). So läuft die Anfrage asynchron weiter und du kannst die fertige Antwort später abrufen.

Wert Verhalten
default Für die zurückgegebenen Suchergebnisse gilt das standardmäßige Token-Budget. Dasselbe gilt, wenn du return_token_budget weglässt.
unlimited Hebt das standardmäßige Token-Budget für die Ergebnisse dieses Suchlaufs auf.

Dieser Parameter gilt nur für das gehostete Tool web_search der Responses API, wenn du die Websuche mit Reasoning-Modellen ab GPT-5 verwendest. Er ändert das Kontextfenster der Suche nicht. Für die Websuche ohne Reasoning, ältere Zugriffswege über die Search API, die Websuche in Containern, Suchmodelle in Chat Completions und web_search_preview gilt er nicht. Zulässig sind nur default und unlimited. Die API lehnt null, Zahlen und andere Zeichenfolgen ab.

Längere Websuchen ausführen
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": { "effort": "xhigh" },
    "tools": [
      {
        "type": "web_search",
        "return_token_budget": "unlimited"
      }
    ],
    "input": "Research the economic impact of semaglutide on global healthcare systems.\n\nDo:\n- Include specific figures, trends, statistics, and measurable outcomes.\n- Prioritize reliable, up-to-date sources: peer-reviewed research, health organizations (e.g., WHO, CDC), regulatory agencies, or pharmaceutical earnings reports.\n- Include inline citations and return all source metadata.\n\nBe analytical, avoid generalities, and ensure that each section supports data-backed reasoning that could inform healthcare policy or financial modeling."
  }'

Nach Domain filtern

Mit Domainfiltern kannst du die Ergebnisse der Websuche auf bestimmte Domains beschränken. Über den Parameter filters kannst du bis zu 100 Einträge für allowed_domains oder bis zu 100 Einträge für blocked_domains angeben. Lass bei den Domains das HTTP- oder HTTPS-Präfix weg. Verwende zum Beispiel openai.com statt https://openai.com/. Der Filter erfasst auch die Subdomains der angegebenen Domains. Domainfilter sind nur in der Responses API mit dem Tool web_search verfügbar.

Quellen

Im Feld sources findest du alle URLs, die während einer Websuche abgerufen wurden. Die Quellenverweise im Text nennen nur die relevantesten Belege. Das Feld sources liefert dagegen die vollständige Liste der URLs, die das Modell für seine Antwort herangezogen hat. Oft gibt es mehr Quellen als Quellenverweise. Hier erscheinen auch Echtzeitfeeds von Drittanbietern mit den Kennzeichnungen oai-sports, oai-weather oder oai-finance. Das Feld sources ist bei beiden Tools verfügbar, sowohl bei web_search als auch bei web_search_preview.

Quellen auflisten
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "reasoning": { "effort": "low" },
    "tools": [
      {
        "type": "web_search",
        "filters": {
          "allowed_domains": [
            "pubmed.ncbi.nlm.nih.gov",
            "clinicaltrials.gov",
            "www.who.int",
            "www.cdc.gov",
            "www.fda.gov"
          ],
          "blocked_domains": [
            "reddit.com",
            "quora.com",
            "wikipedia.org"
          ]
        }
      }
    ],
    "tool_choice": "auto",
    "include": ["web_search_call.action.sources"],
    "input": "Please perform a web search on how semaglutide is used in the treatment of diabetes."
  }'

Ergebnisse der Bildersuche

Die Websuche kann neben Texttreffern auch Bilder liefern. Nutze die Bildersuche, wenn deine Anwendung aktuelle Bilder oder Bildmaterial aus dem Web benötigt, etwa Produktfotos, Aufnahmen von Sehenswürdigkeiten, Orten oder Veranstaltungen oder visuelle Referenzen.

Für die Bildersuche muss search_content_types den Wert image enthalten. Ergänze text, wenn du auch Texttreffer benötigst, die dem Modell helfen, die gefundenen Bilder zusammenzufassen, zu ordnen oder zu erläutern.

Mit image_settings steuerst du die Bildersuche:

  • max_results: Gib die gewünschte Anzahl der Bildtreffer als positive Zahl an.
  • caption: Fordere kurze Bildbeschreibungen an, sofern sie verfügbar sind.

Um die Rohdaten der Bildtreffer einzusehen, gib web_search_call.results in der Anfrage an und lies web_search_call.results[] aus der Antwort aus. Die API liefert Bildtreffer getrennt von der Nachricht des Assistenten. Lies das Element web_search_call daher direkt aus, wenn deine Anwendung die URLs oder Metadaten benötigt.

Nach Bildern suchen
import OpenAI from "openai";
const client = new OpenAI();

const tools: OpenAI.Responses.Tool[] = [
  {
    type: "web_search",
    // @ts-expect-error The published SDK omits the documented image-search options.
    search_content_types: ["image", "text"],
    image_settings: {
      max_results: 3,
      caption: true,
    },
  },
];

const response = await client.responses.create({
  model: "gpt-6-astra",
  reasoning: { effort: "low" },
  tools,
  include: ["web_search_call.results"],
  input:
    "Search for recent images and supporting text sources about the Golden Gate Bridge at sunset.",
});

console.log(response.output);

Jedes Element vom Typ image_result enthält:

  • image_url: Die kanonische URL des gefundenen Bildes.
  • source_website_url: Die Seite, auf der das Bild gefunden wurde.
  • thumbnail_url: Die URL eines Vorschaubildes, sofern verfügbar.
  • caption: Eine kurze Bildunterschrift oder Beschreibung, sofern verfügbar.
{
  "output": [
    {
      "type": "web_search_call",
      "status": "completed",
      "results": [
        {
          "type": "image_result",
          "image_url": "https://cdn.example/golden-gate-sunset.jpg",
          "thumbnail_url": "https://cdn.example/golden-gate-sunset-thumb.jpg",
          "source_website_url": "https://example.com/source-page",
          "caption": "Golden Gate Bridge at sunset"
        }
      ]
    }
  ]
}

Standort der suchenden Person

Für geografisch passendere Suchergebnisse kannst du den ungefähren Standort der suchenden Person angeben. Verwende dazu eine oder mehrere Angaben zu Land, Stadt, Region und Zeitzone.

  • Die Felder city und region akzeptieren Freitext, zum Beispiel Minneapolis für die Stadt und Minnesota für die Region.
  • Das Feld country erwartet einen ISO-Ländercode aus zwei Buchstaben, zum Beispiel US.
  • Das Feld timezone erwartet eine IANA-Zeitzone wie America/Chicago.
Standort für die Suche angeben
import OpenAI from "openai";
const openai = new OpenAI();

const response = await openai.responses.create({
  model: "gpt-6-astra",
  tools: [
    {
      type: "web_search",
      user_location: {
        type: "approximate",
        country: "GB",
        city: "London",
        region: "London",
      },
    },
  ],
  input: "What are the best restaurants near me?",
});
console.log(response.output_text);

Livezugriff auf das Internet

In der Responses API kannst du steuern, ob das Tool für die Websuche Inhalte live abruft oder ausschließlich zwischengespeicherte oder indexierte Ergebnisse verwendet.

  • Setze external_web_access: false beim Tool web_search, um die Suche offline ausschließlich mit zwischengespeicherten Ergebnissen auszuführen.
  • Ohne diese Einstellung gilt der Standardwert true (Livezugriff).
  • Vorschauvarianten (web_search_preview) ignorieren diesen Parameter und verhalten sich so, als wäre external_web_access auf true gesetzt.
Livezugriff auf das Internet steuern
curl "https://api.openai.com/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [
      { "type": "web_search", "external_web_access": false }
    ],
    "tool_choice": "auto",
    "input": "Find when the Eiffel Tower opened to the public and cite the source."
  }'

Einschränkungen

Chat Completions API

Die Chat Completions API unterstützt für die Websuche ausschließlich spezialisierte Suchmodelle. Diese Modelle unterstützen keine Funktionen des Tools web_search der Responses API wie Domainfilter, vollständige Quellenlisten oder die Steuerung des Livezugriffs und des Token-Budgets für zurückgegebene Ergebnisse.

Modell Kontextfenster Einschränkung
gpt-5-search-api 200.000 Nutzt die Suche über Chat Completions

Responses API

Verwende das gehostete Tool web_search. Die Responses API akzeptiert für ältere Integrationen weiterhin web_search_preview. Verwende für neue Integrationen web_search.

Das Kontextfenster der Websuche ist auf 128.000 Token begrenzt, auch wenn das zugrunde liegende Modell ein größeres Kontextfenster hat. Wie groß das Kontextfenster von gpt-6-astra oder einem anderen unterstützten Modell ist, erfährst du auf der jeweiligen Modellseite.

  • gpt-5.4 kann bei einem Reasoning-Aufwand von none Ergebnisse geringerer Qualität liefern.
  • Für die Websuche in der Responses API gelten die gestaffelten Ratenlimits des zugrunde liegenden Modells.
  • web_search_preview unterstützt weder filters noch return_token_budget und ignoriert external_web_access.
  • Mit tool_choice: "auto" ist die Suche optional. Wenn eine Suche erforderlich ist, verwende tool_choice: "required" oder wähle das Tool für die Websuche ausdrücklich aus.

Nutzungshinweise

API-VerfügbarkeitRatenlimitsHinweise

Es gelten die gestaffelten Ratenlimits des Modells, das du mit dem Tool verwendest.

Preise
ZDR und Datenresidenz