From def505355ce73ccbce4b8955087e1e9381600df7 Mon Sep 17 00:00:00 2001 From: Cesar Garcia <128240629+Chesars@users.noreply.github.com> Date: Sat, 7 Feb 2026 05:39:47 -0300 Subject: [PATCH] docs(web_search): add gpt-5-search-api usage examples for SDK and AI Gateway (#20616) - Document two OpenAI web search approaches: search models (/chat/completions) vs web_search_preview tool (/responses) - Add gpt-5-search-api examples across all sections in web_search.md - Update /responses examples to use gpt-5 with web_search_preview tool - Add OpenAI Web Search Models section to providers/openai.md - Add web search example to providers/openai/responses_api.md --- docs/my-website/docs/completion/web_search.md | 117 ++++++++++++------ docs/my-website/docs/providers/openai.md | 65 +++++++++- .../docs/providers/openai/responses_api.md | 18 +++ 3 files changed, 160 insertions(+), 40 deletions(-) diff --git a/docs/my-website/docs/completion/web_search.md b/docs/my-website/docs/completion/web_search.md index 9ba66c730f0..1f5ba2dee4e 100644 --- a/docs/my-website/docs/completion/web_search.md +++ b/docs/my-website/docs/completion/web_search.md @@ -18,7 +18,7 @@ Each provider uses their own search backend: | Provider | Search Engine | Notes | |----------|---------------|-------| -| **OpenAI** (`gpt-4o-search-preview`, `gpt-4o-mini-search-preview`, `gpt-5-search-api`) | OpenAI's internal search | Real-time web data | +| **OpenAI** (`gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview`) | OpenAI's internal search | Real-time web data | | **xAI** (`grok-3`) | xAI's search + X/Twitter | Real-time social media data | | **Google AI/Vertex** (`gemini-2.0-flash`) | **Google Search** | Uses actual Google search results | | **Anthropic** (`claude-3-5-sonnet`) | Anthropic's web search | Real-time web data | @@ -45,6 +45,19 @@ Use `web_search_options` when you need to: **Anthropic Web Search Models**: Claude models that support web search: `claude-3-5-sonnet-latest`, `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-latest`, `claude-3-5-haiku-20241022`, `claude-3-7-sonnet-20250219` ::: +## OpenAI Web Search: Two Approaches + +OpenAI offers two distinct ways to use web search depending on the endpoint and model: + +| Approach | Endpoint | Models | How to enable | +|----------|----------|--------|---------------| +| **Search Models** | `/chat/completions` | `gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview` | Pass `web_search_options` parameter | +| **Web Search Tool** | `/responses` | `gpt-5`, `gpt-4.1`, `gpt-4o`, and other regular models | Pass `web_search_preview` tool | + +:::tip Search models search automatically +Search models like `gpt-5-search-api` **automatically search the web** even without the `web_search_options` parameter. Use `web_search_options` to set `search_context_size` (`"low"`, `"medium"`, `"high"`) or specify `user_location` for localized results. +::: + ## `/chat/completions` (litellm.completion) ### Quick Start @@ -56,7 +69,7 @@ Use `web_search_options` when you need to: from litellm import completion response = completion( - model="openai/gpt-4o-search-preview", + model="openai/gpt-5-search-api", messages=[ { "role": "user", @@ -76,31 +89,36 @@ response = completion( ```yaml model_list: - # OpenAI + # OpenAI search models + - model_name: gpt-5-search-api + litellm_params: + model: openai/gpt-5-search-api + api_key: os.environ/OPENAI_API_KEY + - model_name: gpt-4o-search-preview litellm_params: model: openai/gpt-4o-search-preview api_key: os.environ/OPENAI_API_KEY - + # xAI - model_name: grok-3 litellm_params: model: xai/grok-3 api_key: os.environ/XAI_API_KEY - + # Anthropic - model_name: claude-3-5-sonnet-latest litellm_params: model: anthropic/claude-3-5-sonnet-latest api_key: os.environ/ANTHROPIC_API_KEY - + # VertexAI - model_name: gemini-2-flash litellm_params: model: gemini-2.0-flash vertex_project: your-project-id vertex_location: us-central1 - + # Google AI Studio - model_name: gemini-2-flash-studio litellm_params: @@ -108,13 +126,13 @@ model_list: api_key: os.environ/GOOGLE_API_KEY ``` -2. Start the proxy +2. Start the proxy ```bash litellm --config /path/to/config.yaml ``` -3. Test it! +3. Test it! ```python showLineNumbers from openai import OpenAI @@ -126,13 +144,18 @@ client = OpenAI( ) response = client.chat.completions.create( - model="grok-3", # or any other web search enabled model + model="gpt-5-search-api", # or any other web search enabled model messages=[ { "role": "user", "content": "What was a positive news story from today?" } - ] + ], + extra_body={ + "web_search_options": { + "search_context_size": "medium" + } + } ) ``` @@ -149,7 +172,7 @@ from litellm import completion # Customize search context size response = completion( - model="openai/gpt-4o-search-preview", + model="openai/gpt-5-search-api", messages=[ { "role": "user", @@ -257,6 +280,12 @@ response = client.chat.completions.create( ## `/responses` (litellm.responses) +Use the `web_search_preview` tool with models like `gpt-5`, `gpt-4.1`, `gpt-4o`, etc. + +:::info +Search-dedicated models like `gpt-5-search-api` and `gpt-4o-search-preview` do **not** support the `/responses` endpoint. Use them with `/chat/completions` + `web_search_options` instead (see above). +::: + ### Quick Start @@ -266,18 +295,14 @@ response = client.chat.completions.create( from litellm import responses response = responses( - model="openai/gpt-4o", - input=[ - { - "role": "user", - "content": "What was a positive news story from today?" - } - ], + model="openai/gpt-5", + input="What is the capital of France?", tools=[{ "type": "web_search_preview" # enables web search with default medium context size }] ) ``` + @@ -285,19 +310,24 @@ response = responses( ```yaml model_list: - - model_name: gpt-4o + - model_name: gpt-5 litellm_params: - model: openai/gpt-4o + model: openai/gpt-5 + api_key: os.environ/OPENAI_API_KEY + + - model_name: gpt-4.1 + litellm_params: + model: openai/gpt-4.1 api_key: os.environ/OPENAI_API_KEY ``` -2. Start the proxy +2. Start the proxy ```bash litellm --config /path/to/config.yaml ``` -3. Test it! +3. Test it! ```python showLineNumbers from openai import OpenAI @@ -309,11 +339,11 @@ client = OpenAI( ) response = client.responses.create( - model="gpt-4o", + model="gpt-5", tools=[{ "type": "web_search_preview" }], - input="What was a positive news story from today?", + input="What is the capital of France?", ) print(response.output_text) @@ -331,13 +361,8 @@ from litellm import responses # Customize search context size response = responses( - model="openai/gpt-4o", - input=[ - { - "role": "user", - "content": "What was a positive news story from today?" - } - ], + model="openai/gpt-5", + input="What is the capital of France?", tools=[{ "type": "web_search_preview", "search_context_size": "low" # Options: "low", "medium" (default), "high" @@ -358,12 +383,12 @@ client = OpenAI( # Customize search context size response = client.responses.create( - model="gpt-4o", + model="gpt-5", tools=[{ "type": "web_search_preview", "search_context_size": "low" # Options: "low", "medium" (default), "high" }], - input="What was a positive news story from today?", + input="What is the capital of France?", ) print(response.output_text) @@ -417,14 +442,14 @@ model_list: web_search_options: search_context_size: "high" # Options: "low", "medium", "high" - # Different context size for different models - - model_name: gpt-4o-search-preview + # OpenAI search model with custom context size + - model_name: gpt-5-search-api litellm_params: - model: openai/gpt-4o-search-preview + model: openai/gpt-5-search-api api_key: os.environ/OPENAI_API_KEY web_search_options: search_context_size: "low" - + # Gemini with medium context (default) - model_name: gemini-2-flash litellm_params: @@ -449,6 +474,7 @@ Use `litellm.supports_web_search(model="model_name")` -> returns `True` if model ```python showLineNumbers # Check OpenAI models +assert litellm.supports_web_search(model="openai/gpt-5-search-api") == True assert litellm.supports_web_search(model="openai/gpt-4o-search-preview") == True # Check xAI models @@ -472,13 +498,20 @@ assert litellm.supports_web_search(model="gemini/gemini-2.0-flash") == True ```yaml model_list: # OpenAI + - model_name: gpt-5-search-api + litellm_params: + model: openai/gpt-5-search-api + api_key: os.environ/OPENAI_API_KEY + model_info: + supports_web_search: True + - model_name: gpt-4o-search-preview litellm_params: model: openai/gpt-4o-search-preview api_key: os.environ/OPENAI_API_KEY model_info: supports_web_search: True - + # xAI - model_name: grok-3 litellm_params: @@ -533,6 +566,12 @@ Expected Response ```json showLineNumbers { "data": [ + { + "model_group": "gpt-5-search-api", + "providers": ["openai"], + "max_tokens": 128000, + "supports_web_search": true + }, { "model_group": "gpt-4o-search-preview", "providers": ["openai"], diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index 80645a51ac5..23940e1c54e 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/docs/my-website/docs/providers/openai.md @@ -230,7 +230,70 @@ os.environ["OPENAI_BASE_URL"] = "https://your_host/v1" # OPTIONAL These also support the `OPENAI_BASE_URL` environment variable, which can be used to specify a custom API endpoint. -## OpenAI Vision Models +### OpenAI Web Search Models + +OpenAI has two ways to use web search, depending on the endpoint: + +| Approach | Endpoint | Models | How to enable | +|----------|----------|--------|---------------| +| **Search Models** | `/chat/completions` | `gpt-5-search-api`, `gpt-4o-search-preview`, `gpt-4o-mini-search-preview` | Pass `web_search_options` parameter | +| **Web Search Tool** | `/responses` | `gpt-5`, `gpt-4.1`, `gpt-4o`, and other regular models | Pass `web_search_preview` tool | + + + + +```python showLineNumbers +from litellm import completion + +response = completion( + model="openai/gpt-5-search-api", + messages=[{"role": "user", "content": "What is the capital of France?"}], + web_search_options={ + "search_context_size": "medium" # Options: "low", "medium", "high" + } +) +``` + + + + +```python showLineNumbers +from litellm import responses + +response = responses( + model="openai/gpt-5", + input="What is the capital of France?", + tools=[{ + "type": "web_search_preview", + "search_context_size": "low" + }] +) +``` + + + + +```yaml +model_list: + # Search model for /chat/completions + - model_name: gpt-5-search-api + litellm_params: + model: openai/gpt-5-search-api + api_key: os.environ/OPENAI_API_KEY + + # Regular model for /responses with web_search_preview tool + - model_name: gpt-5 + litellm_params: + model: openai/gpt-5 + api_key: os.environ/OPENAI_API_KEY +``` + + + + +For full details, see the [Web Search guide](../completion/web_search.md). + +## OpenAI Vision Models | Model Name | Function Call | |-----------------------|-----------------------------------------------------------------| | gpt-4o | `response = completion(model="gpt-4o", messages=messages)` | diff --git a/docs/my-website/docs/providers/openai/responses_api.md b/docs/my-website/docs/providers/openai/responses_api.md index 75eab1afac5..7799c93ccf2 100644 --- a/docs/my-website/docs/providers/openai/responses_api.md +++ b/docs/my-website/docs/providers/openai/responses_api.md @@ -37,6 +37,24 @@ for event in response: print(event) ``` +#### Web Search +```python showLineNumbers title="OpenAI Responses with Web Search" +import litellm + +response = litellm.responses( + model="openai/gpt-5", + input="What is the capital of France?", + tools=[{ + "type": "web_search_preview", + "search_context_size": "medium" # Options: "low", "medium", "high" + }] +) + +print(response) +``` + +For full details, see the [Web Search guide](../../completion/web_search.md). + #### Image Generation with Streaming ```python showLineNumbers title="OpenAI Streaming Image Generation" import litellm