[Fix] gpt-5.5 reasoning_effort capability flags + add supports_low_reasoning_effort

[mateo-berri]

Relevant issues

Follow-up to #26449 (merged). Live testing against OpenAI's Chat Completions API on 2026-04-24 surfaced two capability-flag gaps for the GPT-5.5 family:

1. supports_minimal_reasoning_effort was set to true on all four entries — wrong. OpenAI rejects minimal on both gpt-5.5 and gpt-5.5-pro.
2. gpt-5.5-pro additionally rejects reasoning_effort="low" (only accepts medium, high, xhigh). The current JSON schema had no supports_low_reasoning_effort flag to express this constraint.

$ curl https://api.openai.com/v1/chat/completions -d \
    '{"model":"gpt-5.5","reasoning_effort":"minimal", ...}'
HTTP/1.1 400  "Unsupported value: 'reasoning_effort' does not support 'minimal' with this model.
              Supported values are: 'none', 'low', 'medium', 'high', and 'xhigh'."

$ curl https://api.openai.com/v1/chat/completions -d \
    '{"model":"gpt-5.5-pro","reasoning_effort":"minimal", ...}'
HTTP/1.1 400  "Unsupported value: 'minimal' is not supported with the 'gpt-5.5-pro' model.
              Supported values are: 'medium', 'high', and 'xhigh'."

$ curl https://api.openai.com/v1/chat/completions -d \
    '{"model":"gpt-5.5-pro","reasoning_effort":"low", ...}'
HTTP/1.1 400  "Unsupported value: 'low' is not supported with the 'gpt-5.5-pro' model.
              Supported values are: 'medium', 'high', and 'xhigh'."

Without these fixes, drop_params=True users see an avoidable 400 round-trip; drop_params=False users get the same 400 surfaced from OpenAI.

Pre-Submission checklist

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Screenshots / Proof of Fix

Live verification against OpenAI (after this PR)

Proxy with drop_params: True:

=== T1: gpt-5.5-pro + reasoning_effort=low  (drop_params strips before dispatch) ===
HTTP=200  → "LOW"

=== T2: gpt-5.5 + reasoning_effort=low  (allowed) ===
HTTP=200  → "LOW"

=== T3: gpt-5.5-pro + reasoning_effort=medium  (allowed) ===
HTTP=200  → "MED"

=== T4: gpt-5.5 + reasoning_effort=minimal  (drop_params strips) ===
HTTP=200  → "MIN"

=== T5: gpt-5.5-pro + reasoning_effort=minimal  (drop_params strips) ===
HTTP=200  → "MIN"

With drop_params: False, every rejected combination raises litellm.utils.UnsupportedParamsError locally before hitting OpenAI.

Test results

$ uv run pytest tests/test_litellm/llms/openai/test_gpt5_transformation.py \
                tests/test_litellm/llms/openai/test_is_model_gpt_5_model.py \
                tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py
177 passed in 1.72s

Type

🐛 Bug Fix

Changes

1. JSON: supports_minimal_reasoning_effort: false on all four GPT-5.5 entries

gpt-5.5, gpt-5.5-2026-04-23, gpt-5.5-pro, gpt-5.5-pro-2026-04-23 in both model_prices_and_context_window.json and litellm/model_prices_and_context_window_backup.json.

2. New supports_low_reasoning_effort capability flag

• litellm/types/utils.py: add field to ModelInfoBase.
• litellm/utils.py: thread the field through the ModelInfoBase constructor in get_model_info.
• litellm/llms/openai/chat/gpt_5_transformation.py: extend the existing minimal opt-out branch in map_openai_params to also cover low, using the same _is_reasoning_effort_level_explicitly_disabled helper. Default behavior unchanged for models without the flag (low passes through as before).
• JSON: supports_low_reasoning_effort: false set on gpt-5.5-pro and gpt-5.5-pro-2026-04-23 only.

3. Tests

tests/test_litellm/llms/openai/test_gpt5_transformation.py:

• test_gpt5_5_pro_rejects_reasoning_effort_low
• test_gpt5_5_pro_dated_rejects_reasoning_effort_low
• test_gpt5_5_pro_drops_reasoning_effort_low_when_requested
• test_gpt5_5_chat_allows_reasoning_effort_low
• test_gpt5_unknown_model_passes_through_low
• test_gpt5_low_explicitly_disabled_check

tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py:

• test_gpt55_reasoning_effort_flags_match_live_openai_api — pins all four entries' supports_{none,minimal,xhigh}_reasoning_effort to OpenAI's actual API contract.

Out of scope

• Azure entries (azure/gpt-5.5, azure/gpt-5.5-pro) — Microsoft hasn't shipped GPT-5.5 on Azure yet (latest is GPT-5.4 series). Tracked separately in branch litellm_hotfix_gpt-5-5-azure.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ mateo-berri
❌ cursoragent
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[veria-ai]

Model capability flags for reasoning_effort levels

This PR adds a supports_low_reasoning_effort capability flag, updates gpt-5.5 model entries to correctly disable minimal/low reasoning effort where unsupported, and extends the existing opt-out validation logic to cover low alongside minimal. Also includes a minor Vertex AI schema normalization fix for arrays missing items. All changes are confined to parameter validation, model metadata, and tests with no security-relevant surface area.

---

Status: 0 open
Risk: 1/10

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing litellm_hotfix_gpt-5.5-minimal-flag (c333838) with main (d21e90f)}

[greptile-apps]

Greptile Summary

This PR fixes two capability-flag gaps for the GPT-5.5 model family: corrects supports_minimal_reasoning_effort from true to false on all four entries, and introduces a new supports_low_reasoning_effort flag (set to false on gpt-5.5-pro variants) so LiteLLM can reject or drop unsupported reasoning_effort values locally before hitting OpenAI's API. The implementation correctly uses the existing opt-out pattern (_is_reasoning_effort_level_explicitly_disabled) and keeps the JSON, type definitions, utils threading, and schema validator all in sync.

Confidence Score: 5/5

Safe to merge — changes are additive, isolated to GPT-5.5 capability flags, and backed by live API evidence and targeted unit tests.

Only P2 findings; the logic change is minimal and follows the established opt-out pattern already in the codebase. Both JSON files and all type-plumbing are kept in sync.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/llms/openai/chat/gpt_5_transformation.py	Extends the opt-out elif branch to also cover "low" alongside "minimal", using the same _is_reasoning_effort_level_explicitly_disabled helper — correct and consistent with the existing pattern.
litellm/types/utils.py	Adds supports_low_reasoning_effort: Optional[bool] to ProviderSpecificModelInfo; inherited correctly by ModelInfoBase.
litellm/utils.py	Threads supports_low_reasoning_effort from model cost map into ModelInfoBase constructor in _get_model_info_helper, matching the pattern of existing reasoning-effort fields.
model_prices_and_context_window.json	Flips supports_minimal_reasoning_effort to false on all four GPT-5.5 entries and adds supports_low_reasoning_effort: false to gpt-5.5-pro variants only — consistent with live API evidence.
litellm/model_prices_and_context_window_backup.json	Same changes as the primary JSON — backup kept in sync correctly.
tests/test_litellm/llms/openai/test_gpt5_transformation.py	Adds six new unit tests covering gpt-5.5-pro low rejection, drop_params behavior, gpt-5.5 allowance, and unknown-model pass-through — all using mocked model-info, no real network calls.
tests/test_litellm/litellm_core_utils/llm_cost_calc/test_llm_cost_calc_utils.py	Adds regression test pinning reasoning-effort flags to live API observations; does not assert supports_low_reasoning_effort for gpt-5.5-pro, leaving the new flag uncovered by the parametrized test.
tests/test_litellm/test_utils.py	Adds supports_low_reasoning_effort to the JSON schema validator — correctly keeps the schema in sync with the new field.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[map_openai_params called] --> B{effective_effort?}
    B -->|xhigh| C{_supports_reasoning_effort_level?}
    C -->|false| D{drop_params?}
    D -->|yes| E[drop reasoning_effort]
    D -->|no| F[raise UnsupportedParamsError]
    C -->|true| G[pass through]
    B -->|minimal or low| H{_is_reasoning_effort_level_explicitly_disabled?\nlooks up supports_minimal/low_reasoning_effort in JSON}
    H -->|true = flag is false in JSON| I{drop_params?}
    I -->|yes| J[drop reasoning_effort]
    I -->|no| K[raise UnsupportedParamsError]
    H -->|false = flag missing or true| L[pass through]
    B -->|other| M[pass through]

    subgraph JSON flags
        N["gpt-5.5: supports_minimal=false"]
        O["gpt-5.5-pro: supports_minimal=false, supports_low=false, supports_none=false"]
    end

Loading

_{Reviews (3): Last reviewed commit: "test: register supports_low_reasoning_ef..." | Re-trigger Greptile}

[greptile-apps]

Missing env var teardown pollutes later tests

os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] is set to "True" and litellm.model_cost is overwritten, but neither is restored after the test. If a test running later in the same process expects the default (remote-fetched) cost map, it will silently get the local backup instead. The same pattern exists in test_generic_cost_per_token_gpt55_pro, so this wasn't introduced here, but adding the same unguarded pattern again compounds the issue.

A monkeypatch fixture or pytest.fixture with yield + cleanup would prevent leaking into the test suite.

Suggested change

	os.environ["LITELLM_LOCAL_MODEL_COST_MAP"] = "True"
	litellm.model_cost = litellm.get_model_cost_map(url="")
	monkeypatch.setenv("LITELLM_LOCAL_MODEL_COST_MAP", "True")
	litellm.model_cost = litellm.get_model_cost_map(url="")

(requires adding monkeypatch as a parameter to the test function)

[Sameerlite]

nit, please change the base to litellm_internal_staging, I can approve it after that

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/llms/vertex_ai/common_utils.py	50.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Sameerlite]

LGTM, thanks

[oss-pr-review-agent-shin]

🤖 litellm-agent: Merged into staging branch litellm_agent_oss_staging_05_06_2026. Staging PR: #27256

---

Triage Summary
Corrects the reasoning_effort capability flags for gpt-5.5 and gpt-5.5-pro in both model price JSON files, flipping supports_minimal_reasoning_effort from true to false and adding supports_low_reasoning_effort: false for the pro variants. Extends the transformation logic in gpt_5_transformation.py to treat 'low' the same as 'minimal' in the opt-out blocking path, adds supports_low_reasoning_effort to ProviderSpecificModelInfo and the model info helper, fixes an unrelated Vertex AI array schema edge case in common_utils.py, and adds unit tests pinning the new flags and low-effort rejection b…

Merge Confidence: 5/5 ✅ READY
Ready to ship.

All checks green. Greptile 5/5, no blocking pattern findings, CircleCI passed.