feat(openai): Add verbosity parameter support for GPT-5 family models (#16660)

OpenAI's GPT-5 model family supports a verbosity parameter to control
the length and detail of responses. This parameter accepts three values:
'low', 'medium', or 'high'.

Changes:
- Added verbosity parameter to completion() and acompletion() signatures
- Added verbosity to DEFAULT_CHAT_COMPLETION_PARAM_VALUES in constants.py
- Added verbosity to get_optional_params() in utils.py
- Added verbosity to GPT-5 supported params list
- Updated OpenAI docs with verbosity usage examples
- Added comprehensive test for verbosity parameter

Supported models: gpt-5, gpt-5.1, gpt-5-mini, gpt-5-nano, gpt-5-codex, gpt-5-pro

docs/my-website/docs/providers/openai.md

@@ -486,6 +486,53 @@ curl -X POST 'http://0.0.0.0:4000/chat/completions' \
 
 See [OpenAI Reasoning documentation](https://platform.openai.com/docs/guides/reasoning) for more details on organization verification requirements.
 
+### Verbosity Control for GPT-5 Models
+
+The `verbosity` parameter controls the length and detail of responses from GPT-5 family models. It accepts three values: `"low"`, `"medium"`, or `"high"`.
+
+**Supported models:** All GPT-5 family models (`gpt-5`, `gpt-5.1`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-codex`, `gpt-5-pro`)
+
+**Use cases:**
+- **`"low"`**: Best for concise answers or simple code generation (e.g., SQL queries)
+- **`"medium"`**: Default - balanced output length
+- **`"high"`**: Use when you need thorough explanations or extensive code refactoring
+
+<Tabs>
+<TabItem value="sdk" label="SDK">
+```python
+import litellm
+
+# Low verbosity - concise responses
+response = litellm.completion(
+    model="gpt-5.1",
+    messages=[{"role": "user", "content": "Write a function to reverse a string"}],
+    verbosity="low"
+)
+
+# High verbosity - detailed responses
+response = litellm.completion(
+    model="gpt-5.1",
+    messages=[{"role": "user", "content": "Explain how neural networks work"}],
+    verbosity="high"
+)
+```
+</TabItem>
+
+<TabItem value="proxy" label="PROXY">
+```bash
+curl -X POST 'http://0.0.0.0:4000/chat/completions' \
+-H 'Content-Type: application/json' \
+-H 'Authorization: Bearer sk-1234' \
+-d '{
+    "model": "gpt-5.1",
+    "messages": [{"role": "user", "content": "Write a function to reverse a string"}],
+    "verbosity": "low"
+}'
+```
+</TabItem>
+</Tabs>
+
+
 ## OpenAI Chat Completion to Responses API Bridge
 
 Call any Responses API model from OpenAI's `/chat/completions` endpoint. 

litellm/constants.py

@@ -475,6 +475,7 @@ DEFAULT_CHAT_COMPLETION_PARAM_VALUES = {
     "additional_drop_params": None,
     "messages": None,
     "reasoning_effort": None,
+    "verbosity": None,
     "thinking": None,
     "web_search_options": None,
     "service_tier": None,

litellm/llms/openai/chat/gpt_5_transformation.py

@@ -30,7 +30,7 @@ class OpenAIGPT5Config(OpenAIGPTConfig):
         from litellm.utils import supports_tool_choice
 
         base_gpt_series_params = super().get_supported_openai_params(model=model)
-        gpt_5_only_params = ["reasoning_effort"]
+        gpt_5_only_params = ["reasoning_effort", "verbosity"]
         base_gpt_series_params.extend(gpt_5_only_params)
         if not supports_tool_choice(model=model):
             base_gpt_series_params.remove("tool_choice")

litellm/main.py

@@ -390,6 +390,7 @@ async def acompletion(
     reasoning_effort: Optional[
         Literal["none", "minimal", "low", "medium", "high", "default"]
     ] = None,
+    verbosity: Optional[Literal["low", "medium", "high"]] = None,
     safety_identifier: Optional[str] = None,
     service_tier: Optional[str] = None,
     # set api_base, api_version, api_key
@@ -961,6 +962,7 @@ def completion(  # type: ignore # noqa: PLR0915
     reasoning_effort: Optional[
         Literal["none", "minimal", "low", "medium", "high", "default"]
     ] = None,
+    verbosity: Optional[Literal["low", "medium", "high"]] = None,
     response_format: Optional[Union[dict, Type[BaseModel]]] = None,
     seed: Optional[int] = None,
     tools: Optional[List] = None,

litellm/utils.py

@@ -3383,6 +3383,7 @@ def get_optional_params(  # noqa: PLR0915
     drop_params=None,
     allowed_openai_params: Optional[List[str]] = None,
     reasoning_effort=None,
+    verbosity=None,
     additional_drop_params=None,
     messages: Optional[List[AllMessageValues]] = None,
     thinking: Optional[AnthropicThinkingParam] = None,

tests/test_litellm/llms/openai/test_gpt5_transformation.py

@@ -155,6 +155,32 @@ def test_gpt5_codex_supports_function_calling(config: OpenAIConfig):
     assert "tools" in supported_params
 
 
+def test_gpt5_verbosity_parameter(config: OpenAIConfig):
+    """Test that verbosity parameter passes through correctly for GPT-5 models.
+
+    The verbosity parameter controls output length and detail for GPT-5 family models.
+    Supported values: 'low', 'medium', 'high'
+    Supported models: gpt-5, gpt-5.1, gpt-5-mini, gpt-5-nano, gpt-5-codex, gpt-5-pro
+    """
+    # Test all valid verbosity values
+    for verbosity_level in ["low", "medium", "high"]:
+        params = config.map_openai_params(
+            non_default_params={"verbosity": verbosity_level},
+            optional_params={},
+            model="gpt-5.1",
+            drop_params=False,
+        )
+        assert params["verbosity"] == verbosity_level
+
+    # Test with different GPT-5 models
+    for model in ["gpt-5", "gpt-5.1", "gpt-5-mini", "gpt-5-nano", "gpt-5-codex"]:
+        params = config.map_openai_params(
+            non_default_params={"verbosity": "low"},
+            optional_params={},
+            model=model,
+            drop_params=False,
+        )
+        assert params["verbosity"] == "low"
 def test_gpt5_1_reasoning_effort_none(config: OpenAIConfig):
     """Test that GPT-5.1 supports reasoning_effort='none' parameter.