3 causas raízes do erro thinking_level not supported no Gemini 2.5 Flash

Ao chamar o gemini-2.5-flash, você encontrou o erro Thinking level is not supported for this model, mas ao mudar para o gemini-3-flash-preview tudo funcionou normalmente? Essa é uma mudança no design de parâmetros introduzida pela Google Gemini API na atualização geracional do modelo. Este artigo analisará sistematicamente as diferenças fundamentais no suporte aos parâmetros do modo de pensamento entre o Gemini 2.5 e o 3.0.

Valor Central: Ao ler este artigo, você entenderá as diferenças essenciais no design dos parâmetros do modo de pensamento das séries Gemini 2.5 e 3.0, dominará os métodos de configuração corretos e evitará falhas nas chamadas de API causadas pelo uso misto de parâmetros.

Principais Pontos da Evolução dos Parâmetros do Modo de Pensamento do Gemini

Diferenças de Design entre Gemini 2.5 e 3.0 no Modo de Pensamento

Diferença Principal: A série Gemini 2.5 utiliza thinking_budget (sistema de orçamento de tokens), enquanto a série Gemini 3.0 utiliza thinking_level (sistema de níveis semânticos). Esses dois parâmetros são totalmente incompatíveis, e o uso na versão errada do modelo resultará em um erro 400 Bad Request.

A principal razão pela qual o Google introduziu o thinking_level no Gemini 3.0 é simplificar a complexidade da configuração e aumentar a eficiência da inferência. O sistema de orçamento de tokens do Gemini 2.5 exige que os desenvolvedores estimem com precisão a quantidade de tokens de pensamento, enquanto o sistema de níveis do Gemini 3.0 abstrai essa complexidade em 4 níveis semânticos. O modelo aloca internamente o orçamento ideal de tokens, alcançando uma velocidade de inferência até 2 vezes maior.

💡 Sugestão Técnica: No desenvolvimento real, recomendamos usar a plataforma APIYI (apiyi.com) para realizar testes de troca de modelo. A plataforma oferece uma interface de API unificada, suportando todas as séries de modelos Gemini 2.5 e 3.0, facilitando a verificação rápida da compatibilidade e do efeito prático de diferentes parâmetros do modo de pensamento.

Causa Raiz 1: A série Gemini 2.5 não suporta o parâmetro thinking_level

Isolamento geracional no design de parâmetros da API

Os modelos da série Gemini 2.5 (incluindo Pro, Flash e Flash-Lite) não reconhecem de forma alguma o parâmetro thinking_level em seu design de API. Ao passar o parâmetro thinking_level ao chamar o gemini-2.5-flash, a API retornará o seguinte erro:

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

Mecanismo de acionamento do erro:

• A camada de validação da API do modelo Gemini 2.5 não contém a definição do parâmetro thinking_level.
• Qualquer requisição que contenha thinking_level será rejeitada diretamente, sem tentativa de mapeamento para thinking_budget.
• Este é um isolamento de parâmetros codificado rigidamente (hardcoded), sem conversão automática ou compatibilidade retroativa.

Parâmetro correto para a série Gemini 2.5: thinking_budget

Especificação de parâmetros do Gemini 2.5 Flash:

# 正确配置示例
extra_body = {
    "thinking_budget": -1  # 动态思考模式
}

# 或禁用思考
extra_body = {
    "thinking_budget": 0  # 完全禁用
}

# 或精确控制
extra_body = {
    "thinking_budget": 2048  # 精确 2048 token 预算
}

Intervalo de valores de thinking_budget para o Gemini 2.5 Flash:

🎯 Sugestão de escolha: Ao mudar para o Gemini 2.5 Flash, recomenda-se testar primeiro o impacto de diferentes valores do parâmetro thinking_budget na qualidade da resposta e na latência através da plataforma APIYI (apiyi.com). A plataforma permite alternar rapidamente as configurações de parâmetros, facilitando encontrar o valor de orçamento mais adequado para o seu cenário de negócio.

Causa Raiz 2: A série Gemini 3.0 não suporta o parâmetro thinking_budget

Incompatibilidade futura no design de parâmetros

Embora a documentação oficial do Google afirme que o Gemini 3.0 ainda aceita o parâmetro thinking_budget para fins de compatibilidade retroativa, testes reais mostram que:

• O uso de thinking_budget pode levar a uma queda de desempenho
• A documentação oficial recomenda explicitamente o uso de thinking_level
• Algumas implementações de API podem rejeitar completamente o thinking_budget

Parâmetro correto para o Gemini 3.0 Flash: thinking_level

# 正确配置示例
extra_body = {
    "thinking_level": "medium"  # 中等强度推理
}

# 或最小思考 (接近禁用)
extra_body = {
    "thinking_level": "minimal"  # 最小思考模式
}

# 或高强度推理 (默认)
extra_body = {
    "thinking_level": "high"  # 深度推理
}

Explicação dos níveis de thinking_level para o Gemini 3.0 Flash:

Restrições especiais do Gemini 3.0 Pro

Importante: O Gemini 3.0 Pro não permite desativar completamente o modo de pensamento; mesmo configurando thinking_level: "low", ele manterá uma certa capacidade de raciocínio. Se precisar de uma resposta sem pensamento para obter velocidade máxima, você deve usar o thinking_budget: 0 do Gemini 2.5 Flash.

# Gemini 3.0 Pro 可用等级 (仅 2 种)
extra_body = {
    "thinking_level": "low"   # 最低等级 (仍有推理)
}

# 或
extra_body = {
    "thinking_level": "high"  # 默认高强度推理
}

💰 Otimização de custos: Para projetos sensíveis ao orçamento que precisam desativar completamente o modo de pensamento para reduzir custos, recomenda-se chamar a API do Gemini 2.5 Flash através da plataforma APIYI (apiyi.com). A plataforma oferece métodos de faturamento flexíveis e preços mais competitivos, sendo ideal para cenários que exigem controle preciso de custos.

Causa Raiz 3: Restrições de Parâmetros para Modelos de Imagem e Variantes Especiais

O modelo Gemini 2.5 Flash Image não suporta o modo de pensamento

Descoberta importante: Modelos de visão como o gemini-2.5-flash-image não suportam de forma alguma qualquer parâmetro de modo de pensamento, seja thinking_budget ou thinking_level.

Exemplo de erro:

# Ao chamar o gemini-2.5-flash-image
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": "Analise esta imagem"}],
    extra_body={
        "thinking_budget": -1  # ❌ Erro: O modelo de imagem não suporta isso
    }
)
# Retorna o erro: "This model doesn't support thinking"

Forma correta:

# Ao chamar modelos de imagem, não envie nenhum parâmetro de pensamento
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[{"role": "user", "content": "Analise esta imagem"}],
    # ✅ Não envie thinking_budget ou thinking_level
)

Valores padrão especiais do Gemini 2.5 Flash-Lite

Principais diferenças entre o Gemini 2.5 Flash-Lite e a versão Flash padrão:

• Modo de pensamento desativado por padrão (thinking_budget: 0)
• É necessário configurar explicitamente o thinking_budget com um valor diferente de zero para ativar o pensamento
• Intervalo de orçamento suportado: 512-24576 tokens

# Ativando o modo de pensamento no Gemini 2.5 Flash-Lite
extra_body = {
    "thinking_budget": 512  # Valor mínimo não nulo para ativar o pensamento leve
}

🚀 Início Rápido: Recomendamos usar a plataforma APIYI (apiyi.com) para testar rapidamente a compatibilidade dos parâmetros de pensamento em diferentes modelos. A plataforma oferece acesso imediato a toda a série de modelos Gemini, sem necessidade de configurações complexas — você faz a integração e a validação dos parâmetros em menos de 5 minutos.

Solução 1: Baseada em uma função de adaptação de parâmetros por versão do modelo

Seletor inteligente de parâmetros (Suporte a toda a linha Gemini)

def get_gemini_thinking_config(model_name: str, intensity: str = "medium") -> dict:
    """
    Seleciona automaticamente os parâmetros corretos do modo de raciocínio com base no nome do modelo Gemini.

    Args:
        model_name: Nome do modelo Gemini
        intensity: Intensidade do raciocínio ("none", "minimal", "low", "medium", "high", "dynamic")

    Returns:
        Dicionário de parâmetros adequado para extra_body; retorna um dicionário vazio se o modelo não suportar raciocínio.
    """

    # Lista de modelos Gemini 3.0
    gemini_3_models = [
        "gemini-3.0-flash-preview", "gemini-3.0-pro-preview",
        "gemini-3-flash", "gemini-3-pro"
    ]

    # Lista de modelos padrão Gemini 2.5
    gemini_2_5_models = [
        "gemini-2.5-flash", "gemini-2.5-pro",
        "gemini-2.5-flash-lite", "gemini-2-flash", "gemini-2-pro"
    ]

    # Lista de modelos de imagem (não suportam raciocínio)
    image_models = [
        "gemini-2.5-flash-image", "gemini-flash-image",
        "gemini-pro-vision"
    ]

    # Verifica se é um modelo de imagem
    if any(img_model in model_name for img_model in image_models):
        print(f"⚠️ Aviso: {model_name} não suporta parâmetros de modo de raciocínio, retornando configuração vazia")
        return {}

    # A linha Gemini 3.0 usa thinking_level
    if any(m in model_name for m in gemini_3_models):
        level_map = {
            "none": "minimal",      # O 3.0 não permite desativar totalmente, usa-se minimal
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "dynamic": "high"
        }

        # O Gemini 3.0 Pro suporta apenas low e high
        if "pro" in model_name.lower():
            if intensity in ["none", "minimal", "low"]:
                return {"thinking_level": "low"}
            else:
                return {"thinking_level": "high"}

        # O Gemini 3.0 Flash suporta todos os 4 níveis
        return {"thinking_level": level_map.get(intensity, "medium")}

    # A linha Gemini 2.5 usa thinking_budget
    elif any(m in model_name for m in gemini_2_5_models):
        budget_map = {
            "none": 0,           # Desativa completamente
            "minimal": 512,      # Orçamento mínimo
            "low": 2048,         # Baixa intensidade
            "medium": 8192,      # Média intensidade
            "high": 16384,       # Alta intensidade
            "dynamic": -1        # Adaptação dinâmica
        }

        budget = budget_map.get(intensity, -1)

        # O Gemini 2.5 Pro não permite desativação (mínimo 128)
        if "pro" in model_name.lower() and budget == 0:
            print(f"⚠️ Aviso: {model_name} não suporta desativar o raciocínio, ajustando automaticamente para o valor mínimo de 128")
            budget = 128

        # O valor mínimo para o Gemini 2.5 Flash-Lite é 512
        if "lite" in model_name.lower() and budget > 0 and budget < 512:
            print(f"⚠️ Aviso: O orçamento mínimo para {model_name} é 512, ajustando automaticamente")
            budget = 512

        return {"thinking_budget": budget}

    else:
        print(f"⚠️ Aviso: Modelo desconhecido {model_name}, usando parâmetros padrão do Gemini 3.0")
        return {"thinking_level": "medium"}


# Exemplo de uso
import openai

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

# Testando 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"Configuração {model_2_5}: {config_2_5}")
# Saída: Configuração gemini-2.5-flash: {'thinking_budget': -1}

response_2_5 = client.chat.completions.create(
    model=model_2_5,
    messages=[{"role": "user", "content": "Explique o entrelaçamento quântico"}],
    extra_body=config_2_5
)

# Testando 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"Configuração {model_3_0}: {config_3_0}")
# Saída: Configuração gemini-3.0-flash-preview: {'thinking_level': 'medium'}

response_3_0 = client.chat.completions.create(
    model=model_3_0,
    messages=[{"role": "user", "content": "Explique o entrelaçamento quântico"}],
    extra_body=config_3_0
)

# Testando modelo de imagem
model_image = "gemini-2.5-flash-image"
config_image = get_gemini_thinking_config(model_image, intensity="high")
print(f"Configuração {model_image}: {config_image}")
# Saída: ⚠️ Aviso: gemini-2.5-flash-image não suporta parâmetros de modo de raciocínio, retornando configuração vazia
# Saída: Configuração gemini-2.5-flash-image: {}

💡 Melhor Prática: Em cenários onde é necessário alternar dinamicamente entre modelos Gemini, recomendamos realizar testes de adaptação de parâmetros através da plataforma APIYI (apiyi.com). A plataforma oferece suporte completo às séries Gemini 2.5 e 3.0, facilitando a validação da qualidade das respostas e das diferenças de custo em diversas configurações.

Solução 2: Estratégia de migração do Gemini 2.5 para o 3.0

Tabela de correspondência de parâmetros de modo de raciocínio

Exemplo de código para migração

def migrate_to_gemini_3(old_model: str, old_config: dict) -> tuple[str, dict]:
    """
    Migra do Gemini 2.5 para o Gemini 3.0

    Args:
        old_model: Nome do modelo Gemini 2.5
        old_config: Configuração extra_body do Gemini 2.5

    Returns:
        (Novo nome do modelo, Novo dicionário de configuração)
    """
    # Mapeamento de nomes de modelos
    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")

    # Conversão de parâmetros
    if "thinking_budget" in old_config:
        budget = old_config["thinking_budget"]

        # Converte para 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 suporta apenas 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:
        # Configuração padrão
        new_config = {"thinking_level": "medium"}

    return new_model, new_config


# Exemplo de migração
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"Antes da migração: {old_model} {old_config}")
print(f"Depois da migração: {new_model} {new_config}")
# Saída:
# Antes da migração: gemini-2.5-flash {'thinking_budget': -1}
# Depois da migração: gemini-3.0-flash-preview {'thinking_level': 'high'}

# Chamada usando a nova configuração
response = client.chat.completions.create(
    model=new_model,
    messages=[{"role": "user", "content": "Sua pergunta"}],
    extra_body=new_config
)

🎯 Sugestão de Migração: Ao migrar do Gemini 2.5 para o 3.0, recomendamos realizar primeiro um teste A/B através da plataforma APIYI (apiyi.com). A plataforma permite alternar versões de modelos rapidamente, facilitando a comparação da qualidade da resposta, latência e diferença de custos para garantir uma migração suave.

Perguntas Frequentes

# Código incorreto (apenas para o 3.0)
extra_body = {
    "thinking_level": "medium"  # ❌ O 2.5 não reconhece
}

# Código correto (para o 2.5)
extra_body = {
    "thinking_budget": 8192  # ✅ O 2.5 utiliza budget
}

# Apenas o Gemini 2.5 Flash suporta desativação total
model = "gemini-2.5-flash"
extra_body = {
    "thinking_budget": 0  # Desativa completamente o pensamento
}

# ❌ Modelos de imagem não suportam nenhum parâmetro de pensamento
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[...],
    extra_body={
        "thinking_budget": -1  # Causará um erro
    }
)

# ✅ Ao chamar modelos de imagem, não envie parâmetros de pensamento
response = client.chat.completions.create(
    model="gemini-2.5-flash-image",
    messages=[...],
    # Não passe extra_body ou passe apenas parâmetros que não sejam de pensamento
)

Resumo

Pontos fundamentais sobre o erro thinking_level not supported no Gemini 2.5 Flash:

1. Isolamento de Parâmetros: O Gemini 2.5 só aceita thinking_budget, e o 3.0 só aceita thinking_level. Eles são totalmente incompatíveis entre si.
2. Identificação do Modelo: Identifique a versão pelo nome do modelo: use thinking_budget para a série 2.5 e thinking_level para a série 3.0.
3. Restrições de Modelos de Imagem: Modelos focados em imagem (como o gemini-2.5-flash-image) não aceitam nenhum parâmetro de modo de pensamento.
4. Diferenças na Desativação: Somente o Gemini 2.5 Flash permite desativar o pensamento totalmente (thinking_budget: 0); na série 3.0, o mínimo é o nível minimal.
5. Estratégia de Migração: Ao migrar do 2.5 para o 3.0, você precisará mapear o thinking_budget para o thinking_level e considerar as mudanças em desempenho e custo.

Recomendamos utilizar a APIYI (apiyi.com) para validar rapidamente a compatibilidade dos parâmetros de pensamento e o efeito real em diferentes modelos. A plataforma suporta toda a linha Gemini, oferecendo uma interface unificada e faturamento flexível, ideal para testes comparativos e implantação em produção.

Autor: Equipe Técnica APIYI | Se tiver dúvidas técnicas, visite a APIYI (apiyi.com) para explorar mais soluções de integração de modelos de IA.