3 root causes for Gemini 2.5 Flash error thinking_level not supported

Ever run into a Thinking level is not supported for this model error when calling gemini-2.5-flash, even though it works perfectly for gemini-3-flash-preview? This is due to a design change Google made to Gemini API parameters during its generational upgrade. In this post, we'll do a systematic breakdown of the fundamental differences in thinking mode parameter support between Gemini 2.5 and 3.0.

Core Value: By the end of this article, you'll understand the essential differences in how the Gemini 2.5 and 3.0 series handle thinking mode parameters. You'll also learn the correct configuration methods to avoid API call failures caused by mixing up these parameters.

Key Points of Gemini Thinking Mode Parameter Evolution

The Logic Behind the Switch: Gemini 2.5 vs 3.0

The fundamental difference: The Gemini 2.5 series uses thinking_budget (a token budget system), while the Gemini 3.0 series uses thinking_level (a semantic level system). These two parameters are completely incompatible. If you use the wrong one for the model version you're calling, you'll trigger a 400 Bad Request error.

Google introduced thinking_level in Gemini 3.0 primarily to simplify configuration complexity and boost reasoning efficiency. The token budget system in Gemini 2.5 required developers to estimate exactly how many thinking tokens were needed. In contrast, Gemini 3.0's level-based system abstracts this complexity into four semantic levels. The model then internally allocates the optimal token budget, resulting in a 2x boost in reasoning speed.

💡 Tech Tip: For your actual development, we recommend using the APIYI (apiyi.com) platform for model switching and testing. The platform provides a unified API interface that supports the entire Gemini 2.5 and 3.0 series, making it easy to quickly verify compatibility and see the actual results of different thinking mode parameters.

Root Cause 1: Gemini 2.5 Series Doesn't Support the thinking_level Parameter

Generational Isolation in API Parameter Design

The Gemini 2.5 series (including Pro, Flash, and Flash-Lite) completely fails to recognize the thinking_level parameter in its API design. When you pass the thinking_level parameter while calling gemini-2.5-flash, the API returns the following error:

{
  "error": {
    "message": "Thinking level is not supported for this model.",
    "type": "upstream_error",
    "code": 400
  }
}

Error Trigger Mechanism:

• The API validation layer for Gemini 2.5 models doesn't include a definition for the thinking_level parameter.
• Any request containing thinking_level is rejected outright; the system doesn't attempt to map it to thinking_budget.
• This is hard-coded parameter isolation, meaning there's no automatic conversion or backward compatibility.

The Correct Parameter for Gemini 2.5: thinking_budget

Gemini 2.5 Flash Parameter Specification:

# Correct configuration example
extra_body = {
    "thinking_budget": -1  # Dynamic thinking mode
}

# Or disable thinking
extra_body = {
    "thinking_budget": 0  # Fully disabled
}

# Or precise control
extra_body = {
    "thinking_budget": 2048  # Exact 2048 token budget
}

Gemini 2.5 Flash thinking_budget Value Ranges:

🎯 Pro Tip: When switching to Gemini 2.5 Flash, it's a good idea to first test how different thinking_budget values impact response quality and latency using the APIYI (apiyi.com) platform. This platform lets you quickly toggle parameter configs, making it easy to find the perfect budget for your specific use case.

Root Cause 2: Gemini 3.0 Series Doesn't Support the thinking_budget Parameter

Forward Incompatibility in Parameter Design

While official Google documentation claims Gemini 3.0 still accepts the thinking_budget parameter for backward compatibility, actual testing shows:

• Using thinking_budget can lead to performance degradation.
• The official docs explicitly recommend using thinking_level.
• Some API implementations might reject thinking_budget entirely.

The Correct Parameter for Gemini 3.0 Flash: thinking_level

# Correct configuration example
extra_body = {
    "thinking_level": "medium"  # Medium intensity reasoning
}

# Or minimal thinking (closest to disabled)
extra_body = {
    "thinking_level": "minimal"  # Minimal thinking mode
}

# Or high intensity reasoning (default)
extra_body = {
    "thinking_level": "high"  # Deep reasoning
}

Gemini 3.0 Flash thinking_level Descriptions:

Special Restrictions for Gemini 3.0 Pro

Important: Gemini 3.0 Pro does not support fully disabling thinking mode. Even if you set thinking_level: "low", it will still retain a certain level of reasoning capability. If you need a zero-thinking response for maximum speed, you'll have to stick with Gemini 2.5 Flash and use thinking_budget: 0.

# Available levels for Gemini 3.0 Pro (only 2 options)
extra_body = {
    "thinking_level": "low"   # Lowest level (still includes reasoning)
}

# Or
extra_body = {
    "thinking_level": "high"  # Default high-intensity reasoning
}

💰 Cost Optimization: For budget-sensitive projects that need to fully disable thinking mode to cut costs, we recommend calling the Gemini 2.5 Flash API via the APIYI (apiyi.com) platform. The platform offers flexible billing and more competitive pricing, perfect for scenarios that require precise cost control.

Root Cause 3: Parameter Limits for Image Models and Special Variants

Gemini 2.5 Flash Image Model Doesn't Support Thinking Mode

Key Finding: Visual models like gemini-2.5-flash-image don't support any thinking mode parameters at all, whether it's thinking_budget or thinking_level.

Wrong way to do it:

# When calling gemini-2.5-flash-image
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": "Analyze this image"}],
    extra_body={
        "thinking_budget": -1  # ❌ Error: Image models don't support this
    }
)
# Returns the error: "This model doesn't support thinking"

Right way to do it:

# When calling image models, don't pass any thinking parameters
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": "Analyze this image"}],
    # ✅ Don't pass thinking_budget or thinking_level
)

Special Defaults for Gemini 2.5 Flash-Lite

The core differences for Gemini 2.5 Flash-Lite are:

• Thinking mode is disabled by default (thinking_budget: 0)
• You must explicitly set thinking_budget to a non-zero value to enable thinking
• Supported budget range: 512-24576 tokens

# Enabling thinking mode for Gemini 2.5 Flash-Lite
extra_body = {
    "thinking_budget": 512  # Minimum non-zero value to enable lightweight thinking
}

🚀 Quick Start: We recommend using the APIYI (apiyi.com) platform to quickly test the thinking parameter compatibility of different models. The platform offers out-of-the-box interfaces for the entire Gemini series, so you won't need complex configurations—you can finish integration and parameter validation in just 5 minutes.

Solution 1: Parameter Adaptation Function Based on Model Version

Smart Parameter Selector (Supports all model series)

def get_gemini_thinking_config(model_name: str, intensity: str = "medium") -> dict:
    """
    Automatically selects the correct thinking mode parameters based on the Gemini model name.

    Args:
        model_name: Gemini model name
        intensity: Thinking intensity ("none", "minimal", "low", "medium", "high", "dynamic")

    Returns:
        A dictionary of parameters suitable for extra_body. Returns an empty dict if the model doesn't support thinking.
    """

    # Gemini 3.0 model list
    gemini_3_models = [
        "gemini-3.0-flash-preview", "gemini-3.0-pro-preview",
        "gemini-3-flash", "gemini-3-pro"
    ]

    # Gemini 2.5 standard model list
    gemini_2_5_models = [
        "gemini-2.5-flash", "gemini-2.5-pro",
        "gemini-2.5-flash-lite", "gemini-2-flash", "gemini-2-pro"
    ]

    # Image model list (thinking not supported)
    image_models = [
        "gemini-2.5-flash-image", "gemini-flash-image",
        "gemini-pro-vision"
    ]

    # Check if it's an image model
    if any(img_model in model_name for img_model in image_models):
        print(f"⚠️ Warning: {model_name} doesn't support thinking mode parameters. Returning empty config.")
        return {}

    # Gemini 3.0 series uses thinking_level
    if any(m in model_name for m in gemini_3_models):
        level_map = {
            "none": "minimal",      # 3.0 can't be fully disabled, using minimal
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "dynamic": "high"
        }

        # Gemini 3.0 Pro only supports low and high
        if "pro" in model_name.lower():
            if intensity in ["none", "minimal", "low"]:
                return {"thinking_level": "low"}
            else:
                return {"thinking_level": "high"}

        # Gemini 3.0 Flash supports all 4 levels
        return {"thinking_level": level_map.get(intensity, "medium")}

    # Gemini 2.5 series uses thinking_budget
    elif any(m in model_name for m in gemini_2_5_models):
        budget_map = {
            "none": 0,           # Fully disabled
            "minimal": 512,      # Minimum budget
            "low": 2048,         # Low intensity
            "medium": 8192,      # Medium intensity
            "high": 16384,       # High intensity
            "dynamic": -1        # Dynamic adaptation
        }

        budget = budget_map.get(intensity, -1)

        # Gemini 2.5 Pro doesn't support disabling (minimum 128)
        if "pro" in model_name.lower() and budget == 0:
            print(f"⚠️ Warning: {model_name} doesn't support disabling thinking. Auto-adjusting to minimum 128.")
            budget = 128

        # Gemini 2.5 Flash-Lite minimum value is 512
        if "lite" in model_name.lower() and budget > 0 and budget < 512:
            print(f"⚠️ Warning: {model_name} minimum budget is 512. Auto-adjusting.")
            budget = 512

        return {"thinking_budget": budget}

    else:
        print(f"⚠️ Warning: Unknown model {model_name}. Defaulting to Gemini 3.0 parameters.")
        return {"thinking_level": "medium"}


# Usage Example
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

# Test Gemini 2.5 Flash
model_2_5 = "gemini-2.5-flash"
config_2_5 = get_gemini_thinking_config(model_2_5, intensity="dynamic")
print(f"{model_2_5} Config: {config_2_5}")
# Output: gemini-2.5-flash Config: {'thinking_budget': -1}

response_2_5 = client.chat.completions.create(
    model=model_2_5,
    messages=[{"role": "user", "content": "Explain quantum entanglement"}],
    extra_body=config_2_5
)

# Test Gemini 3.0 Flash
model_3_0 = "gemini-3.0-flash-preview"
config_3_0 = get_gemini_thinking_config(model_3_0, intensity="medium")
print(f"{model_3_0} Config: {config_3_0}")
# Output: gemini-3.0-flash-preview Config: {'thinking_level': 'medium'}

response_3_0 = client.chat.completions.create(
    model=model_3_0,
    messages=[{"role": "user", "content": "Explain quantum entanglement"}],
    extra_body=config_3_0
)

# Test Image Model
model_image = "gemini-2.5-flash-image"
config_image = get_gemini_thinking_config(model_image, intensity="high")
print(f"{model_image} Config: {config_image}")
# Output: ⚠️ Warning: gemini-2.5-flash-image doesn't support thinking mode parameters. Returning empty config.
# Output: gemini-2.5-flash-image Config: {}

💡 Best Practice: If you're in a scenario where you need to switch Gemini models dynamically, I'd recommend testing your parameter adaptations on the APIYI (apiyi.com) platform. It supports the full range of Gemini 2.5 and 3.0 models, making it easy to verify response quality and cost differences across various configurations.

Solution 2: Migration Strategy from Gemini 2.5 to 3.0

Thinking Mode Parameter Migration Comparison Table

Migration Code Example

def migrate_to_gemini_3(old_model: str, old_config: dict) -> tuple[str, dict]:
    """
    Migrate from Gemini 2.5 to Gemini 3.0

    Args:
        old_model: Gemini 2.5 model name
        old_config: extra_body configuration for Gemini 2.5

    Returns:
        (New model name, New configuration dictionary)
    """
    # Model name mapping
    model_map = {
        "gemini-2.5-flash": "gemini-3.0-flash-preview",
        "gemini-2.5-pro": "gemini-3.0-pro-preview",
        "gemini-2-flash": "gemini-3-flash",
        "gemini-2-pro": "gemini-3-pro"
    }

    new_model = model_map.get(old_model, "gemini-3.0-flash-preview")

    # Parameter conversion
    if "thinking_budget" in old_config:
        budget = old_config["thinking_budget"]

        # Convert to thinking_level
        if budget == 0:
            new_level = "minimal"
        elif budget <= 2048:
            new_level = "low"
        elif budget <= 8192:
            new_level = "medium"
        else:
            new_level = "high"

        # Gemini 3.0 Pro only supports low/high
        if "pro" in new_model and new_level in ["minimal", "medium"]:
            new_level = "low" if new_level == "minimal" else "high"

        new_config = {"thinking_level": new_level}
    else:
        # Default configuration
        new_config = {"thinking_level": "medium"}

    return new_model, new_config


# Migration Example
old_model = "gemini-2.5-flash"
old_config = {"thinking_budget": -1}

new_model, new_config = migrate_to_gemini_3(old_model, old_config)
print(f"Before Migration: {old_model} {old_config}")
print(f"After Migration: {new_model} {new_config}")
# Output:
# Before Migration: gemini-2.5-flash {'thinking_budget': -1}
# After Migration: gemini-3.0-flash-preview {'thinking_level': 'high'}

# Call using new configuration
response = client.chat.completions.create(
    model=new_model,
    messages=[{"role": "user", "content": "Your question here"}],
    extra_body=new_config
)

🎯 Migration Advice: When moving from Gemini 2.5 to 3.0, it's a good idea to run some A/B tests on the APIYI (apiyi.com) platform first. The platform lets you switch model versions instantly, so you can compare response quality, latency, and costs to ensure a smooth transition.

FAQ

# Incorrect code (only works for 3.0)
extra_body = {
    "thinking_level": "medium"  # ❌ 2.5 won't recognize this
}

# Correct code (works for 2.5)
extra_body = {
    "thinking_budget": 8192  # ✅ 2.5 uses budget
}

# Only Gemini 2.5 Flash supports fully disabling thinking
model = "gemini-2.5-flash"
extra_body = {
    "thinking_budget": 0  # Completely disables thinking
}

# ❌ Image models don't support any thinking parameters
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[...],
    extra_body={
        "thinking_budget": -1  # This will trigger an error
    }
)

# ✅ Don't pass thinking parameters when calling image models
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[...],
    # Skip extra_body or only pass non-thinking related parameters
)

Summary

Here are the key takeaways for fixing the thinking_level not supported error in Gemini 2.5 Flash:

1. Parameter Isolation: Gemini 2.5 only supports thinking_budget, while 3.0 only supports thinking_level. They aren't interchangeable.
2. Model Identification: Use the model name to determine the version. Use thinking_budget for the 2.5 series and thinking_level for the 3.0 series.
3. Image Model Limits: All image models (like gemini-2.5-flash-image) don't support any thinking mode parameters.
4. Disabling Differences: Only Gemini 2.5 Flash allows you to fully disable thinking (thinking_budget: 0). The 3.0 series only goes as low as minimal.
5. Migration Strategy: When moving from 2.5 to 3.0, you'll need to map thinking_budget to thinking_level and account for changes in performance and cost.

We recommend using APIYI (apiyi.com) to quickly verify parameter compatibility and see how different models behave. The platform supports the entire Gemini lineup with a unified interface and flexible billing, making it perfect for both rapid testing and production deployment.

Author: APIYI Tech Team | If you have any technical questions, feel free to visit APIYI (apiyi.com) for more AI model integration solutions.