From cc72037cec8aaa51dec40fbce360e45b7e2a3e4a Mon Sep 17 00:00:00 2001 From: Cesar Garcia <128240629+Chesars@users.noreply.github.com> Date: Sat, 15 Nov 2025 00:38:27 -0300 Subject: [PATCH] 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 | 47 +++++++++++++++++++ litellm/constants.py | 1 + .../llms/openai/chat/gpt_5_transformation.py | 2 +- litellm/main.py | 2 + litellm/utils.py | 1 + .../llms/openai/test_gpt5_transformation.py | 26 ++++++++++ 6 files changed, 78 insertions(+), 1 deletion(-) diff --git a/docs/my-website/docs/providers/openai.md b/docs/my-website/docs/providers/openai.md index e288f51155..99d17d8b21 100644 --- a/docs/my-website/docs/providers/openai.md +++ b/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 + + + +```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" +) +``` + + + +```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" +}' +``` + + + + ## OpenAI Chat Completion to Responses API Bridge Call any Responses API model from OpenAI's `/chat/completions` endpoint. diff --git a/litellm/constants.py b/litellm/constants.py index d22772c7fb..3f763cad92 100644 --- a/litellm/constants.py +++ b/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, diff --git a/litellm/llms/openai/chat/gpt_5_transformation.py b/litellm/llms/openai/chat/gpt_5_transformation.py index 183f60debb..d18f898cf1 100644 --- a/litellm/llms/openai/chat/gpt_5_transformation.py +++ b/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") diff --git a/litellm/main.py b/litellm/main.py index 23ffa90e2d..7d420bd36b 100644 --- a/litellm/main.py +++ b/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, diff --git a/litellm/utils.py b/litellm/utils.py index ae3de67374..e0cfa6202a 100644 --- a/litellm/utils.py +++ b/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, diff --git a/tests/test_litellm/llms/openai/test_gpt5_transformation.py b/tests/test_litellm/llms/openai/test_gpt5_transformation.py index 42db678d1d..2e1eacce53 100644 --- a/tests/test_litellm/llms/openai/test_gpt5_transformation.py +++ b/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.