fix: resolve max_tokens / max_completion_tokens to one field, tighter value wins

A chat request can carry both output-token fields — most often because a
deployment configures one as a ceiling in litellm_params while the client
sends the other. What reached the provider then depended on dict iteration
order, and was wrong two different ways.

SILENT CEILING OVERRIDE. The provider maps that collapse the two fields
assign the same output key from two branches, so the one iterated last won.
`max_completion_tokens` is second in the `get_optional_params` signature, so
a deployment ceiling silently replaced the caller's request. Measured on the
pre-change tree with max_tokens=50 + max_completion_tokens=64000:

    anthropic     -> {'max_tokens': 64000}
    bedrock       -> {'maxTokens': 64000}
    openai o3     -> {'max_completion_tokens': 64000}
    openai gpt-5  -> {'max_completion_tokens': 64000}

`openai_like` is worse: `replace_max_completion_tokens_with_max_tokens`
overwrites unconditionally, so the ceiling always won.

BOTH FIELDS ON THE WIRE. Providers that forward both unchanged send both.
Azure 2025+ api_versions reject that outright:

    AzureException BadRequestError - Setting 'max_tokens' and
    'max_completion_tokens' at the same time is not supported.

Neither failure is provider-specific in nature, so neither belongs in a
provider transform. `get_optional_params` now resolves the two fields once,
before any mapping, in `litellm_core_utils/max_tokens_params.py`:

  1. Tighter wins. A ceiling can't be raised by a client, and a client's
     tighter request can't be widened to the ceiling.
  2. One field out, chosen by `BaseConfig.get_preferred_max_tokens_param`.
     Default None (either field accepted, caller's choice stands).
     `AzureOpenAIConfig` derives it from the api_version — 2025+ and the v1
     API need `max_completion_tokens`, older versions predate that field and
     need `max_tokens`, so the rename runs in both directions. The o-series
     and gpt-5 configs declare `max_completion_tokens`, which is what makes
     a request carrying both resolve there instead of last-wins.
  3. Never invent a value. A max_tokens of 0 / None / "50" / True does not
     become a max_completion_tokens that truncates every response. It is
     still stripped from a field the provider is known to reject, since an
     unusable value is not a ceiling worth preserving.

A preference for a field the provider does not accept is ignored rather than
forced, so resolution can never leave a request with no ceiling at all.

Also adds `use_max_completion_tokens`, a per-request / per-deployment
directive that overrides the provider detection: True sends
`max_completion_tokens`, False sends `max_tokens`, None (default) keeps
today's detection. It is the authoritative control for deployments whose
requirement can't be inferred from provider + api_version. Plumbed as a
litellm-only param, so it is never forwarded to a provider.

Verified live against a litellm proxy with a capture server standing in for
the provider, client sending max_tokens=50, before/after on the same config:

  deployment                              before              after
  azure 2025 + max_completion_tokens      MCT 16384 + MT 50   MCT 50
  ceiling                                 (Azure 400s)
  azure 2025 + that ceiling and           MCT 16384           MCT 50
  additional_drop_params: [max_tokens]    (caller's 50 gone)
  anthropic + max_completion_tokens       MT 64000            MT 50
  ceiling                                 (caller's 50 gone)
  azure 2025 + use_max_completion_        n/a (ignored)       MT 50
  tokens: false

60 tests. The tighter-wins and Azure-rename tests fail on the previous head.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Also regenerates ui/litellm-dashboard/src/lib/http/schema.d.ts, which the
Check UI API Types Sync workflow verifies against the live proxy spec: adding
the param to GenericLiteLLMParams changes that spec. The same regeneration
picks up a pre-existing /v1/router/models drift already on h2o-main (a route
added without regenerating), so that hunk is here too — without it the check
stays red on any PR touching litellm/types/**.

Author: pseudotensor

litellm/litellm_core_utils/max_tokens_params.py

@@ -0,0 +1,144 @@
+"""Canonicalize the two OpenAI output-token fields onto a single field.
+
+WHY THIS EXISTS
+---------------
+The OpenAI chat schema carries two output-token fields: the original
+``max_tokens`` and its replacement ``max_completion_tokens``. A request can
+arrive with both — most commonly because a proxy deployment configures one of
+them as a ceiling in ``litellm_params`` while the client sends the other. When
+that happens today, what reaches the provider depends on the order the
+provider's ``map_openai_params`` happens to iterate, and the result is wrong in
+two different ways:
+
+  * Providers that collapse both onto one field do so with LAST-WINS
+    semantics, because both branches assign the same output key. ``anthropic``
+    (``max_tokens``) and ``bedrock`` converse (``maxTokens``) both do this, and
+    ``max_completion_tokens`` is iterated second, so a client asking for 50
+    output tokens against a deployment configured with a 64000 ceiling gets
+    64000 — the caller's limit is silently discarded. ``openai_like`` is worse:
+    it replaces unconditionally, so the ceiling always wins.
+
+  * Providers that forward both fields unchanged send both to the API.
+    Azure 2025+ API versions reject that outright:
+
+        AzureException BadRequestError - Setting 'max_tokens' and
+        'max_completion_tokens' at the same time is not supported.
+
+Neither failure mode is provider-specific in nature, so neither belongs in a
+provider transform. This module resolves both fields to one, once, before the
+provider mapping runs.
+
+THE RULES
+---------
+1. TIGHTER WINS. When both fields carry a usable value, the smaller one is
+   kept. A deployment ceiling can therefore never be RAISED by a client, and a
+   client's tighter request can never be widened to the ceiling.
+
+2. ONE FIELD OUT. When a preferred field is known, only that field survives.
+   The preference comes from the provider config
+   (``BaseConfig.get_preferred_max_tokens_param``), or from an explicit
+   per-request/per-deployment ``use_max_completion_tokens`` directive, which
+   overrides the provider's own detection.
+
+3. NEVER INVENT A VALUE. If neither field holds a positive integer, nothing is
+   changed. A ``max_tokens`` of ``0``, ``None``, a string, or a bool must not
+   become a ``max_completion_tokens`` that truncates every response.
+"""
+
+from typing import Any, Dict, Optional, Sequence
+
+MAX_TOKENS_PARAM = "max_tokens"
+MAX_COMPLETION_TOKENS_PARAM = "max_completion_tokens"
+
+MAX_TOKENS_PARAMS = (MAX_TOKENS_PARAM, MAX_COMPLETION_TOKENS_PARAM)
+
+
+def preferred_param_for_directive(
+    use_max_completion_tokens: Optional[bool],
+) -> Optional[str]:
+    """Translate the ``use_max_completion_tokens`` directive to a field name.
+
+    ``None`` means "no directive given" — fall back to provider detection.
+    """
+    if use_max_completion_tokens is None:
+        return None
+    return (
+        MAX_COMPLETION_TOKENS_PARAM
+        if use_max_completion_tokens
+        else MAX_TOKENS_PARAM
+    )
+
+
+def _positive_int(value: Any) -> Optional[int]:
+    """Return ``value`` as a positive int, or None if it isn't one.
+
+    ``bool`` is rejected explicitly because it is an ``int`` subclass.
+    """
+    if isinstance(value, bool) or not isinstance(value, int):
+        return None
+    return value if value > 0 else None
+
+
+def resolve_max_tokens_params(
+    non_default_params: Dict[str, Any],
+    supported_params: Sequence[str],
+    preferred_param: Optional[str] = None,
+) -> Optional[str]:
+    """Collapse ``max_tokens`` / ``max_completion_tokens`` in place.
+
+    Args:
+        non_default_params: mutated in place; the params about to be mapped.
+        supported_params: the params this model/provider accepts. A preference
+            for a field the provider does not accept is ignored rather than
+            forced, so the resolution can never leave a request with no
+            output-token ceiling at all.
+        preferred_param: the field to keep, or None to let the caller's own
+            field stand when only one was sent.
+
+    Returns:
+        The field that survived, or None when nothing was changed.
+    """
+    present = [p for p in MAX_TOKENS_PARAMS if p in non_default_params]
+    if not present:
+        return None
+
+    values = [
+        v
+        for v in (_positive_int(non_default_params[p]) for p in present)
+        if v is not None
+    ]
+    if not values:
+        # Rule 3 — nothing usable to move or tighten. Still strip a field the
+        # provider is known to reject: an unusable value (0, a string) is not a
+        # ceiling worth preserving, and leaving it on a field the provider
+        # rejects turns a garbage request into a guaranteed 400.
+        if preferred_param is not None and preferred_param in supported_params:
+            for param in MAX_TOKENS_PARAMS:
+                if param != preferred_param:
+                    non_default_params.pop(param, None)
+        return None
+    resolved = min(values)
+
+    target: Optional[str] = None
+    if preferred_param is not None and preferred_param in supported_params:
+        target = preferred_param
+    elif len(present) == 1:
+        # One field, no preference: the caller's choice already is canonical.
+        return None
+    else:
+        # Both fields with no provider preference. Collapsing is still
+        # required — leaving both is what makes the last-wins provider maps
+        # pick the looser value. Prefer `max_tokens`: every provider
+        # understands it, and the reasoning-model configs that want
+        # `max_completion_tokens` rename it themselves downstream.
+        target = (
+            MAX_TOKENS_PARAM
+            if MAX_TOKENS_PARAM in supported_params
+            else MAX_COMPLETION_TOKENS_PARAM
+        )
+
+    for param in MAX_TOKENS_PARAMS:
+        if param != target:
+            non_default_params.pop(param, None)
+    non_default_params[target] = resolved
+    return target

litellm/llms/azure/chat/gpt_5_transformation.py

@@ -1,6 +1,6 @@
 """Support for Azure OpenAI gpt-5 model family."""
 
-from typing import List
+from typing import List, Optional
 
 import litellm
 from litellm.exceptions import UnsupportedParamsError
@@ -56,6 +56,17 @@ def is_model_gpt_5_model(cls, model: str) -> bool:
         _normalized = model.split("/")[-1]  # strip provider prefix, e.g. "azure/"
         return ("gpt-5" in model and not _normalized.startswith("gpt-5-chat")) or "gpt5_series" in model
 
+    def get_preferred_max_tokens_param(
+        self, model: str, api_version: Optional[str] = None
+    ) -> Optional[str]:
+        """Always ``max_completion_tokens``, independent of api_version.
+
+        The MRO would otherwise reach ``AzureOpenAIConfig``'s api_version rule
+        first, which would answer ``max_tokens`` for a pre-2025 version — wrong
+        for a gpt-5 deployment, whose ``map_openai_params`` renames it anyway.
+        """
+        return "max_completion_tokens"
+
     def get_supported_openai_params(self, model: str) -> List[str]:
         """Get supported parameters for Azure OpenAI GPT-5 models.
 

litellm/llms/azure/chat/gpt_transformation.py

@@ -9,6 +9,7 @@
 from litellm.llms.base_llm.chat.transformation import BaseLLMException
 from litellm.types.llms.azure import (
     API_VERSION_MONTH_SUPPORTED_RESPONSE_FORMAT,
+    API_VERSION_YEAR_REQUIRING_MAX_COMPLETION_TOKENS,
     API_VERSION_YEAR_SUPPORTED_RESPONSE_FORMAT,
 )
 from litellm.types.utils import ModelResponse
@@ -148,6 +149,34 @@ def _is_response_format_supported_api_version(self, api_version_year: str, api_v
         else:
             return api_month >= supported_month
 
+    def get_preferred_max_tokens_param(
+        self, model: str, api_version: Optional[str] = None
+    ) -> Optional[str]:
+        """Azure's output-token field depends on the api_version.
+
+        2025+ versions (and the v1 API) reject ``max_tokens`` for ALL chat
+        models, not just the o-series, so the caller's value has to travel on
+        ``max_completion_tokens``. Older versions predate that field, so it has
+        to travel on ``max_tokens``.
+
+        Returns None when the api_version isn't a recognizable shape, which
+        leaves the caller's own field untouched.
+        """
+        if api_version is None:
+            return None
+
+        from litellm.llms.azure.common_utils import BaseAzureLLM
+
+        if BaseAzureLLM._is_azure_v1_api_version(api_version):
+            return "max_completion_tokens"
+
+        api_version_year = api_version.split("-")[0]
+        if len(api_version_year) != 4 or not api_version_year.isdigit():
+            return None
+        if int(api_version_year) >= API_VERSION_YEAR_REQUIRING_MAX_COMPLETION_TOKENS:
+            return "max_completion_tokens"
+        return "max_tokens"
+
     def map_openai_params(
         self,
         non_default_params: dict,

litellm/llms/base_llm/chat/transformation.py

@@ -192,6 +192,22 @@ def max_retry_on_unprocessable_entity_error(self) -> int:
     def get_supported_openai_params(self, model: str) -> list:
         pass
 
+    def get_preferred_max_tokens_param(
+        self, model: str, api_version: Optional[str] = None
+    ) -> Optional[str]:
+        """Which output-token field this provider wants on the wire.
+
+        The OpenAI schema has two — ``max_tokens`` and its replacement
+        ``max_completion_tokens`` — and a request can arrive carrying both.
+        Return the one this provider accepts so that only that one is sent;
+        return None (the default) when the provider handles either and the
+        caller's choice should stand.
+
+        See ``litellm.litellm_core_utils.max_tokens_params`` for the resolution
+        this feeds.
+        """
+        return None
+
     def _add_response_format_to_tools(
         self,
         optional_params: dict,

litellm/llms/openai/chat/gpt_5_transformation.py

@@ -188,6 +188,16 @@ def get_supported_openai_params(self, model: str) -> list:
 
         return [param for param in base_gpt_series_params if param not in non_supported_params]
 
+    def get_preferred_max_tokens_param(
+        self, model: str, api_version: Optional[str] = None
+    ) -> Optional[str]:
+        """gpt-5 models take ``max_completion_tokens`` only.
+
+        Same reason as the o-series: the rename below writes the key that the
+        generic mapping overwrites when both fields are present.
+        """
+        return "max_completion_tokens"
+
     def map_openai_params(
         self,
         non_default_params: dict,

litellm/llms/openai/chat/o_series_transformation.py

@@ -87,6 +87,18 @@ def get_supported_openai_params(self, model: str) -> list:
 
         return [param for param in all_openai_params if param not in non_supported_params]
 
+    def get_preferred_max_tokens_param(
+        self, model: str, api_version: Optional[str] = None
+    ) -> Optional[str]:
+        """O-series models take ``max_completion_tokens`` only.
+
+        ``map_openai_params`` below already moves ``max_tokens`` across, but it
+        writes the key that the generic mapping then overwrites when BOTH
+        fields are present. Declaring the preference is what makes a request
+        carrying both resolve to one field holding the tighter value.
+        """
+        return "max_completion_tokens"
+
     def map_openai_params(
         self,
         non_default_params: dict,

litellm/main.py

@@ -5254,6 +5254,10 @@ def completion(  # type: ignore
             "service_tier": service_tier,
             "allowed_openai_params": kwargs.get("allowed_openai_params"),
             "base_model": base_model,
+            # Selects WHICH output-token field is sent (max_tokens vs
+            # max_completion_tokens), overriding the provider's own detection.
+            # Settable per-request or per-deployment via litellm_params.
+            "use_max_completion_tokens": kwargs.get("use_max_completion_tokens"),
         }
         optional_params = get_optional_params(**optional_param_args, **non_default_params)
         processed_non_default_params = pre_process_non_default_params(

litellm/types/llms/azure.py

@@ -1,2 +1,17 @@
 API_VERSION_YEAR_SUPPORTED_RESPONSE_FORMAT = 2024
 API_VERSION_MONTH_SUPPORTED_RESPONSE_FORMAT = 8
+
+# First api_version year in which Azure chat completions reject `max_tokens`
+# in favour of `max_completion_tokens`:
+#
+#     Unsupported parameter: 'max_tokens' is not supported with this model.
+#     Use 'max_completion_tokens' instead.
+#
+# Observed on 2025-04-01-preview against a gpt-4o deployment, i.e. for a plain
+# chat model and not only for the o-series. The boundary is set at the year
+# rather than a specific preview date because Azure rolled the change out
+# across the 2025 preview versions and the v1 (`preview` / `latest` / `v1`)
+# API, and because `max_completion_tokens` is the field Azure documents as
+# current for every 2025 version — so erring on this side of the boundary
+# sends the field Azure asks for.
+API_VERSION_YEAR_REQUIRING_MAX_COMPLETION_TOKENS = 2025

litellm/types/router.py

@@ -245,6 +245,12 @@ class GenericLiteLLMParams(CredentialLiteLLMParams, CustomPricingLiteLLMParams):
         default=False,
         description="Use stored xAI OAuth credentials when no xAI API key is configured.",
     )
+    # Which output-token field this deployment accepts. True -> send
+    # `max_completion_tokens`, False -> send `max_tokens`, None (default) ->
+    # let the provider config decide (for Azure, from the api_version).
+    # Overrides that detection, so it is the authoritative control when a
+    # deployment's requirement can't be inferred from provider + api_version.
+    use_max_completion_tokens: Optional[bool] = None
     model_config = ConfigDict(extra="allow", arbitrary_types_allowed=True)
     merge_reasoning_content_in_choices: Optional[bool] = False
     model_info: Optional[Dict] = None

litellm/types/utils.py

@@ -3210,6 +3210,7 @@ def strip_custom_pricing_fields(cls, model_info: Dict[str, Any]) -> Dict[str, An
         "_litellm_tpm_reserved_model",
         "_litellm_tpm_reserved_scopes",
         "_litellm_tpm_reservation_released",
+        "use_max_completion_tokens",
     ]
     + list(StandardCallbackDynamicParams.__annotations__.keys())
     + list(CustomPricingLiteLLMParams.model_fields.keys())