fix(openai): restrict supported params for gpt-5-search models

gpt-5-search-api models were routed through OpenAIGPT5Config which
listed params like n, temperature, tools, reasoning_effort as supported,
but OpenAI rejects all of these for search models.

Fixes #21572

litellm/llms/openai/chat/gpt_5_transformation.py

@@ -23,6 +23,11 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
         # Don't route it through GPT-5 reasoning-specific parameter restrictions.
         return "gpt-5" in model and "gpt-5-chat" not in model
 
+    @classmethod
+    def is_model_gpt_5_search_model(cls, model: str) -> bool:
+        """Check if the model is a GPT-5 search variant (e.g. gpt-5-search-api)."""
+        return "gpt-5" in model and "search" in model
+
     @classmethod
     def is_model_gpt_5_codex_model(cls, model: str) -> bool:
         """Check if the model is specifically a GPT-5 Codex variant."""
@@ -60,6 +65,23 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
         return model_name.startswith("gpt-5.2")
 
     def get_supported_openai_params(self, model: str) -> list:
+        if self.is_model_gpt_5_search_model(model):
+            return [
+                "max_tokens",
+                "max_completion_tokens",
+                "stream",
+                "stream_options",
+                "web_search_options",
+                "service_tier",
+                "safety_identifier",
+                "response_format",
+                "user",
+                "store",
+                "verbosity",
+                "max_retries",
+                "extra_headers",
+            ]
+
         from litellm.utils import supports_tool_choice
 
         base_gpt_series_params = super().get_supported_openai_params(model=model)
@@ -90,6 +112,18 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
         model: str,
         drop_params: bool,
     ) -> dict:
+        if self.is_model_gpt_5_search_model(model):
+            if "max_tokens" in non_default_params:
+                optional_params["max_completion_tokens"] = non_default_params.pop(
+                    "max_tokens"
+                )
+            return super()._map_openai_params(
+                non_default_params=non_default_params,
+                optional_params=optional_params,
+                model=model,
+                drop_params=drop_params,
+            )
+
         reasoning_effort = (
             non_default_params.get("reasoning_effort")
             or optional_params.get("reasoning_effort")

tests/test_litellm/llms/openai/test_gpt5_transformation.py

@@ -414,3 +414,81 @@ def test_gpt5_2_allows_reasoning_effort_xhigh(config: OpenAIConfig):
         drop_params=False,
     )
     assert params["reasoning_effort"] == "xhigh"
+
+
+# GPT-5-Search specific tests
+def test_gpt5_search_model_detection(gpt5_config: OpenAIGPT5Config):
+    """Test that GPT-5 search models are correctly detected."""
+    assert gpt5_config.is_model_gpt_5_search_model("gpt-5-search-api")
+    assert gpt5_config.is_model_gpt_5_search_model("gpt-5-search-mini-api")
+
+    assert not gpt5_config.is_model_gpt_5_search_model("gpt-5")
+    assert not gpt5_config.is_model_gpt_5_search_model("gpt-5-codex")
+    assert not gpt5_config.is_model_gpt_5_search_model("gpt-5-mini")
+
+
+def test_gpt5_search_supported_params(gpt5_config: OpenAIGPT5Config):
+    """Test that search models do NOT list reasoning/tool params as supported."""
+    supported = gpt5_config.get_supported_openai_params(model="gpt-5-search-api")
+    rejected = [
+        "logit_bias",
+        "modalities",
+        "prediction",
+        "n",
+        "seed",
+        "temperature",
+        "tools",
+        "tool_choice",
+        "function_call",
+        "functions",
+        "parallel_tool_calls",
+        "audio",
+        "reasoning_effort",
+    ]
+    for param in rejected:
+        assert param not in supported, f"{param} should not be supported for search models"
+
+
+def test_gpt5_search_has_expected_params(gpt5_config: OpenAIGPT5Config):
+    """Test that search models DO list the correct supported params."""
+    supported = gpt5_config.get_supported_openai_params(model="gpt-5-search-api")
+    expected = [
+        "max_tokens",
+        "max_completion_tokens",
+        "stream",
+        "stream_options",
+        "web_search_options",
+        "service_tier",
+        "response_format",
+        "user",
+        "store",
+        "verbosity",
+        "extra_headers",
+    ]
+    for param in expected:
+        assert param in supported, f"{param} should be supported for search models"
+
+
+def test_gpt5_search_maps_max_tokens(config: OpenAIConfig):
+    """Test that search models map max_tokens -> max_completion_tokens."""
+    params = config.map_openai_params(
+        non_default_params={"max_tokens": 200},
+        optional_params={},
+        model="gpt-5-search-api",
+        drop_params=False,
+    )
+    assert params["max_completion_tokens"] == 200
+    assert "max_tokens" not in params
+
+
+def test_gpt5_search_drops_unsupported_params(config: OpenAIConfig):
+    """Test that search models drop unsupported params via map_openai_params."""
+    params = config.map_openai_params(
+        non_default_params={"n": 2, "temperature": 0.7, "tools": [{"type": "function"}]},
+        optional_params={},
+        model="gpt-5-search-api",
+        drop_params=True,
+    )
+    assert "n" not in params
+    assert "temperature" not in params
+    assert "tools" not in params