3 méthodes pour résoudre l’erreur de conflit entre thinking_budget et thinking_level de l’API Gemini

Vous rencontrez l'erreur thinking_budget and thinking_level are not supported together en appelant les modèles Gemini 3.0 Pro Preview ou gemini-3-flash-preview ? Il s'agit d'un problème de compatibilité dû à une mise à jour des paramètres entre les différentes versions de l'API Gemini de Google. Cet article analyse la cause profonde de cette erreur sous l'angle de l'évolution de l'API et vous présente la méthode de configuration correcte.

Valeur ajoutée : Après avoir lu cet article, vous saurez configurer correctement les paramètres du mode réflexion pour les modèles Gemini 2.5 et 3.0, évitant ainsi les erreurs d'appel d'API courantes tout en optimisant les performances d'inférence et le contrôle des coûts.

Points clés de l'évolution des paramètres du mode réflexion de l'API Gemini

Différences fondamentales des paramètres de réflexion Gemini

La raison principale pour laquelle Google a introduit le paramètre thinking_level dans Gemini 3.0 est de simplifier l'expérience de configuration pour les développeurs. Alors que le thinking_budget de Gemini 2.5 obligeait les développeurs à estimer précisément le nombre de tokens de réflexion, le thinking_level de Gemini 3.0 abstrait cette complexité en 4 niveaux sémantiques, abaissant ainsi la barrière à l'entrée pour la configuration.

Ce changement de conception reflète un arbitrage de Google dans l'évolution de son API : sacrifier une partie de la précision du contrôle au profit d'une meilleure ergonomie et d'une cohérence accrue entre les modèles. Pour la plupart des applications, l'abstraction offerte par thinking_level est largement suffisante. Le recours à thinking_budget ne se justifie que lorsqu'une optimisation extrême des coûts ou un contrôle très spécifique du budget de tokens est nécessaire.

💡 Conseil technique : Pour vos développements, nous vous suggérons d'effectuer vos tests d'appels d'interface via la plateforme APIYI (apiyi.com). Elle propose une interface API unifiée supportant les modèles Gemini 2.5 Flash, Gemini 3.0 Pro, Gemini 3.0 Flash, etc., ce qui facilite la validation rapide des effets réels et des différences de coûts entre les différentes configurations de mode réflexion.

Cause racine de l'erreur : stratégie de rétrocompatibilité de la conception des paramètres

Analyse du message d'erreur API

{
  "status_code": 400,
  "error": {
    "message": "Unable to submit request because thinking_budget and thinking_level are not supported together.",
    "type": "upstream_error",
    "code": 400
  }
}

L'information clé de cette erreur est que thinking_budget et thinking_level ne peuvent pas exister simultanément. Lorsque Google a introduit de nouveaux paramètres pour Gemini 3.0, il n'a pas totalement abandonné les anciens, mais a adopté une stratégie d'exclusion mutuelle :

• Modèles Gemini 2.5 : acceptent uniquement thinking_budget et ignorent thinking_level.
• Modèles Gemini 3.0 : utilisent en priorité thinking_level, tout en acceptant thinking_budget pour maintenir la compatibilité descendante, mais interdisent la transmission des deux en même temps.
• Condition de déclenchement de l'erreur : la requête API contient à la fois les paramètres thinking_budget et thinking_level.

Pourquoi cette erreur se produit-elle ?

Les développeurs rencontrent généralement cette erreur dans les trois scénarios suivants :

🎯 Conseil de sélection : Lors du changement de version du modèle Gemini, il est recommandé de tester d'abord la compatibilité des paramètres via la plateforme APIYI (apiyi.com). Cette plateforme permet de basculer rapidement entre les modèles des séries Gemini 2.5 et 3.0, facilitant ainsi la comparaison de la qualité des réponses et des différences de latence selon les configurations du mode de réflexion, tout en évitant les conflits de paramètres en production.

3 solutions : choisir les bons paramètres selon la version du modèle

Solution 1 : Configuration du modèle Gemini 2.5 (utiliser thinking_budget)

Modèles concernés : gemini-2.5-flash, gemini-2.5-pro, etc.

Description des paramètres :

• thinking_budget: 0 – Désactive complètement le mode de réflexion, latence et coût minimaux.
• thinking_budget: -1 – Mode de réflexion dynamique, le modèle s'ajuste selon la complexité de la requête.
• thinking_budget: <entier positif> – Spécifie précisément la limite maximale de tokens de réflexion.

Exemple minimaliste

import openai

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

response = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17",
    messages=[{"role": "user", "content": "Explique le principe de l'intrication quantique"}],
    extra_body={
        "thinking_budget": -1  # Mode de réflexion dynamique
    }
)
print(response.choices[0].message.content)

import openai

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

response = client.chat.completions.create(
    model="gemini-2.5-flash-preview-04-17",
    messages=[{"role": "user", "content": "Explique le principe de l'intrication quantique"}],
    extra_body={
        "thinking_budget": -1,  # Mode de réflexion dynamique
        "include_thoughts": True  # Activer le retour du résumé de réflexion
    }
)

# Extraire le contenu de réflexion (si activé)
for part in response.choices[0].message.content:
    if hasattr(part, 'thought') and part.thought:
        print(f"Processus de réflexion : {part.text}")

# Extraire la réponse finale
final_answer = response.choices[0].message.content
print(f"Réponse finale : {final_answer}")

Note : Le modèle Gemini 2.5 sera retiré le 3 mars 2026. Il est conseillé de migrer vers la série Gemini 3.0 dès que possible. Vous pouvez comparer rapidement la qualité des réponses avant et après migration sur la plateforme APIYI (apiyi.com).

Solution 2 : Configuration du modèle Gemini 3.0 (utiliser thinking_level)

Modèles concernés : gemini-3.0-flash-preview, gemini-3.0-pro-preview

Description des paramètres :

• thinking_level: "minimal" – Réflexion minimale, budget proche de zéro, nécessite la transmission de signatures de réflexion (Thought Signatures).
• thinking_level: "low" – Réflexion de faible intensité, adaptée au suivi d'instructions simples et au chat.
• thinking_level: "medium" – Réflexion d'intensité moyenne, adaptée aux tâches de raisonnement général (uniquement supporté par Gemini 3.0 Flash).
• thinking_level: "high" – Réflexion de haute intensité, maximise la profondeur du raisonnement, idéale pour les problèmes complexes (valeur par défaut).

Exemple minimaliste

import openai

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

response = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[{"role": "user", "content": "Analyse la complexité temporelle de ce code"}],
    extra_body={
        "thinking_level": "medium"  # Réflexion d'intensité moyenne
    }
)
print(response.choices[0].message.content)

import openai

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

# Premier tour de dialogue
response_1 = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[{"role": "user", "content": "Conçois un algorithme de cache LRU"}],
    extra_body={
        "thinking_level": "high",
        "include_thoughts": True
    }
)

# Extraire la signature de réflexion (retournée automatiquement par Gemini 3.0)
thought_signatures = []
for part in response_1.choices[0].message.content:
    if hasattr(part, 'thought_signature'):
        thought_signatures.append(part.thought_signature)

# Deuxième tour de dialogue, transmission de la signature pour maintenir la chaîne de raisonnement
response_2 = client.chat.completions.create(
    model="gemini-3.0-flash-preview",
    messages=[
        {"role": "user", "content": "Conçois un algorithme de cache LRU"},
        {"role": "assistant", "content": response_1.choices[0].message.content, "thought_signatures": thought_signatures},
        {"role": "user", "content": "Optimise la complexité spatiale de cet algorithme"}
    ],
    extra_body={
        "thinking_level": "high"
    }
)
print(response_2.choices[0].message.content)

💰 Optimisation des coûts : Pour les projets sensibles au budget, vous pouvez envisager d'utiliser l'API Gemini 3.0 Flash via APIYI (apiyi.com). La plateforme propose une facturation flexible et des tarifs avantageux, idéaux pour les petites et moyennes équipes ainsi que les développeurs individuels. L'utilisation de thinking_level: "low" permet de réduire encore davantage les coûts.

Solution 3 : Stratégie d'adaptation des paramètres pour le basculement dynamique de modèle

Cas d'usage : Nécessité de supporter à la fois les modèles Gemini 2.5 et 3.0 dans le code.

Fonction d'adaptation intelligente des paramètres

def get_thinking_config(model_name: str, complexity: str = "medium") -> dict:
    """
    Sélectionne automatiquement le bon paramètre de mode de réflexion selon la version du modèle.

    Args:
        model_name: Nom du modèle Gemini
        complexity: Complexité de réflexion ("minimal", "low", "medium", "high", "dynamic")

    Returns:
        Dictionnaire de paramètres pour extra_body
    """
    # Liste des modèles Gemini 3.0
    gemini_3_models = [
        "gemini-3.0-flash-preview",
        "gemini-3.0-pro-preview",
        "gemini-3-flash",
        "gemini-3-pro"
    ]

    # Liste des modèles Gemini 2.5
    gemini_2_5_models = [
        "gemini-2.5-flash-preview-04-17",
        "gemini-2.5-flash-lite",
        "gemini-2-flash",
        "gemini-2-flash-lite"
    ]

    # Déterminer la version du modèle
    if any(m in model_name for m in gemini_3_models):
        # Gemini 3.0 utilise thinking_level
        level_map = {
            "minimal": "minimal",
            "low": "low",
            "medium": "medium",
            "high": "high",
            "dynamic": "high"  # Haute intensité par défaut
        }
        return {"thinking_level": level_map.get(complexity, "medium")}

    elif any(m in model_name for m in gemini_2_5_models):
        # Gemini 2.5 utilise thinking_budget
        budget_map = {
            "minimal": 0,
            "low": 512,
            "medium": 2048,
            "high": 8192,
            "dynamic": -1
        }
        return {"thinking_budget": budget_map.get(complexity, -1)}

    else:
        # Modèle inconnu, paramètres Gemini 3.0 par défaut
        return {"thinking_level": "medium"}

# Exemple d'utilisation
import openai

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

model = "gemini-3.0-flash-preview"  # Peut être basculé dynamiquement
thinking_config = get_thinking_config(model, complexity="high")

response = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Votre question"}],
    extra_body=thinking_config
)

🚀 Démarrage rapide : Nous vous recommandons d'utiliser la plateforme APIYI (apiyi.com) pour prototyper rapidement. La plateforme fournit une interface API Gemini prête à l'emploi, sans configuration complexe. L'intégration se fait en 5 minutes et permet de basculer en un clic entre les différents paramètres de réflexion pour comparer les résultats.

Gemini 3.0 : Comprendre le mécanisme des Signatures de Pensée (Thought Signatures)

Qu'est-ce qu'une signature de pensée ?

Les Signatures de Pensée (Thought Signatures) introduites par Gemini 3.0 sont une représentation chiffrée du processus de raisonnement interne du modèle. Lorsque vous activez include_thoughts: true, le modèle renvoie une signature chiffrée de son cheminement intellectuel dans la réponse. Vous pouvez ensuite transmettre ces signatures dans les échanges suivants pour permettre au modèle de maintenir la cohérence de sa chaîne de raisonnement.

Caractéristiques principales :

• Représentation chiffrée : Le contenu de la signature est illisible par l'humain et ne peut être analysé que par le modèle lui-même.
• Maintien de la chaîne de raisonnement : En transmettant la signature lors d'un dialogue multi-tours, le modèle peut poursuivre son raisonnement en se basant sur ses réflexions précédentes.
• Retour forcé : Par défaut, Gemini 3.0 renvoie une signature de pensée, même si elle n'a pas été explicitement demandée.

Scénarios d'utilisation réelle des signatures de pensée

import openai

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

# 第一轮:让模型设计算法
response_1 = client.chat.completions.create(
    model="gemini-3.0-pro-preview",
    messages=[{"role": "user", "content": "设计一个分布式限流算法"}],
    extra_body={
        "thinking_level": "high",
        "include_thoughts": True
    }
)

# 提取思考签名
signatures = []
for part in response_1.choices[0].message.content:
    if hasattr(part, 'thought_signature'):
        signatures.append(part.thought_signature)

# 第二轮:基于之前的推理继续优化
response_2 = client.chat.completions.create(
    model="gemini-3.0-pro-preview",
    messages=[
        {"role": "user", "content": "设计一个分布式限流算法"},
        {
            "role": "assistant",
            "content": response_1.choices[0].message.content,
            "thought_signatures": signatures  # 传递思考签名
        },
        {"role": "user", "content": "如何处理分布式时钟不一致问题?"}
    ],
    extra_body={"thinking_level": "high"}
)

💡 Bonne pratique : Pour les scénarios nécessitant un raisonnement complexe sur plusieurs tours (comme la conception de systèmes, l'optimisation d'algorithmes ou la revue de code), il est recommandé de tester l'impact de la transmission des signatures via la plateforme APIYI (apiyi.com). Cette plateforme prend en charge l'intégralité du mécanisme de signature de pensée de Gemini 3.0, facilitant la validation de la qualité du raisonnement selon les différentes configurations.

Questions Fréquemment Posées

# 仅传递 thinking_level,观察响应
response = client.chat.completions.create(
    model="your-model-name",
    messages=[{"role": "user", "content": "test"}],
    extra_body={"thinking_level": "low"}
)
# 如果返回 400 错误且提示不支持 thinking_level,说明是 Gemini 2.5

Résumé

Points clés concernant les erreurs thinking_budget et thinking_level de l'API Gemini :

1. Exclusivité des paramètres : Gemini 2.5 utilise thinking_budget, alors que Gemini 3.0 utilise thinking_level. Ces deux paramètres ne peuvent pas être envoyés simultanément.
2. Identification du modèle : Identifiez la version via le nom du modèle. La série 2.5 utilise thinking_budget, et la série 3.0 utilise thinking_level.
3. Adaptation dynamique : Utilisez une fonction d'adaptation des paramètres pour sélectionner automatiquement le bon argument en fonction du nom du modèle, évitant ainsi de coder les valeurs en dur.
4. Signatures de réflexion : Gemini 3.0 introduit un mécanisme de signature de réflexion. Pour les scénarios de raisonnement complexes multi-tours, il est nécessaire de transmettre cette signature pour maintenir la continuité de la chaîne de réflexion.
5. Conseil de migration : Gemini 2.5 sera retiré le 3 mars 2026. Nous vous recommandons de migrer vers la série 3.0 le plus tôt possible.

Nous vous recommandons d'utiliser APIYI (apiyi.com) pour valider rapidement l'impact réel des différentes configurations du mode réflexion. Cette plateforme prend en charge toute la gamme des modèles Gemini, propose une interface unifiée et des modes de facturation flexibles, parfaits pour vos tests comparatifs rapides et vos déploiements en production.

Auteur : Équipe technique APIYI | Pour toute question technique, n'hésitez pas à visiter APIYI (apiyi.com) pour découvrir plus de solutions d'intégration de Grand modèle de langage.