Merge pull request #25842 from BerriAI/litellm_docs-gemini3-thinking-defaults

docs(gemini): Gemini 3 thinking_level defaults and release note

docs/my-website/blog/gemini_3/index.md

@@ -479,8 +479,8 @@ For Gemini 3 Pro Preview, LiteLLM automatically maps `reasoning_effort` to the n
 | `"none"` | `"low"` | Gemini 3 cannot fully disable thinking |
 
 #### Default Behavior
+LiteLLM **does not** set `thinking_level` when you omit `reasoning_effort`. The Gemini API applies its **native defaults**, matching a direct call to Google.
 
-If you don't specify `reasoning_effort`, LiteLLM automatically sets `thinking_level="low"` for Gemini 3 models, to avoid high costs. 
 
 ### Example Usage
 
@@ -542,7 +542,7 @@ curl http://localhost:4000/v1/chat/completions \
    - Degraded reasoning performance
    - Failure on complex tasks
 
-3. **Automatic Defaults**: If you don't specify `reasoning_effort`, LiteLLM automatically sets `thinking_level="low"` for optimal performance.
+3. **Thinking defaults come from the API**: If you omit `reasoning_effort`, LiteLLM does **not** override `thinking_level`. Set `reasoning_effort` or native thinking parameters when you want a predictable cost or latency profile (for example `reasoning_effort="low"` for lighter reasoning).
 
 ## Cost Tracking: Prompt Caching & Context Window
 

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

@@ -83,7 +83,7 @@ Note: Reasoning cannot be turned off on Gemini 2.5 Pro models.
 :::
 
 :::tip Gemini 3 Models
-For **Gemini 3+ models** (e.g., `gemini-3-pro-preview`), LiteLLM automatically maps `reasoning_effort` to the new `thinking_level` parameter instead of `thinking_budget`. The `thinking_level` parameter uses `"low"` or `"high"` values for better control over reasoning depth.
+For **Gemini 3+ models** (e.g., `gemini-3-pro-preview`), LiteLLM maps `reasoning_effort` to the `thinking_level` field instead of `thinking_budget` when you set it. Supported levels depend on the model (Flash-family models also support `minimal` and `medium`). If you omit `reasoning_effort`, LiteLLM does **not** send a default `thinking_level` — the request uses the **Gemini API defaults** (Gemini 3 Flash defaults to `high` on the API).
 :::
 
 :::warning Image Models
@@ -104,12 +104,12 @@ For **Gemini 3+ models** (e.g., `gemini-3-pro-preview`), LiteLLM automatically m
 
 | reasoning_effort | thinking_level | Notes |
 | ---------------- | -------------- | ----- |
-| "minimal"        | "low" | Minimizes latency and cost |
+| "minimal"        | `"minimal"` (Flash / some 3.1) or `"low"` | Flash-family IDs use `minimal` when supported |
 | "low"            | "low" | Best for simple instruction following or chat |
-| "medium"         | "high" | Maps to high (medium not yet available) |
+| "medium"         | `"medium"` or `"high"` | `"medium"` where the API supports it; otherwise `"high"` |
 | "high"           | "high" | Maximizes reasoning depth |
-| "disable"        | "low" | Cannot fully disable thinking in Gemini 3 |
-| "none"           | "low" | Cannot fully disable thinking in Gemini 3 |
+| "disable"        | `"minimal"` (Flash) or `"low"` | Cannot fully disable thinking in Gemini 3 |
+| "none"           | `"minimal"` (Flash) or `"low"` | Cannot fully disable thinking in Gemini 3 |
 
 <Tabs>
 <TabItem value="sdk" label="SDK">

docs/my-website/release_notes/v1.82.3/index.md

@@ -262,6 +262,9 @@ pip install litellm==1.82.3
 - **[OpenRouter](../../docs/providers/openrouter)**
     - Image edit support for OpenRouter models - [PR #22403](https://github.com/BerriAI/litellm/pull/22403)
 
+- **[Google Gemini](../../docs/providers/gemini)**
+    - Gemini 3 — no injected default `thinking_level` when `reasoning_effort` is omitted (matches Gemini API; Flash may default to `high` vs old `minimal`) — [Gemini 3 blog](../../blog/gemini_3)
+
 - **[Google Vertex AI](../../docs/providers/vertex)**
     - VIDEO modality token usage tracking in `completion_tokens_details` - [PR #22550](https://github.com/BerriAI/litellm/pull/22550)