Guide de migration d'API Gemini 3.7 Flash vers 3.8 Flash

Google a lancé Gemini 3.8 Flash le 2 septembre 2026, trois semaines après 3.7 Flash, au même prix de lancement et à peu près à la même vitesse. L'ID du modèle est gemini-3.8-flash, sans suffixe de prévisualisation, et sa carte de modèle le décrit comme "basé sur Gemini 3.7 Flash". La plupart des équipes s'attendent donc à un simple échange de ligne. Pour une simple invite de chat, c'est le cas. Pour tout ce qui définit des paramètres de réflexion, ajuste l'échantillonnage ou exécute une boucle d'outils, il y a neuf choses à vérifier, et deux d'entre elles renvoient des erreurs que 3.7 Flash n'a jamais produites.

Ce guide est cette liste de vérification, construite à partir de la page "Quoi de neuf dans Gemini 3.8 Flash" de Google What’s new in Gemini 3.8 Flash et du guide du développeur Gemini 3. Chaque élément présente un fragment avant et après pour les deux formes d'API : l'API Interactions, que Google traite désormais comme le chemin principal, et le point de terminaison hérité generateContent que la plupart des codes 3.7 Flash utilisent encore. Chaque fragment peut être collé dans Apidog et envoyé au point de terminaison en direct avant de toucher la production. Si vous souhaitez d'abord un aperçu du modèle, commencez par ce qu'est Gemini 3.8 Flash.

Une remarque de cadrage avant la liste. Google affirme que 3.8 Flash "travaille plus dur" par conception : sur les tâches complexes, il effectue des étapes de raisonnement plus petites, vérifie son travail et appelle les outils de manière itérative. C'est la source de la plupart de ses gains et aussi la raison pour laquelle une migration nécessite une révision du budget de jetons, et pas seulement une différence de configuration.

Ce qui change et ce qui ne change pas

Source pour les lignes de prix : la page Gemini API pricing page de Google, où les lignes 3.6, 3.7 et 3.8 Flash sont identiques.

Étape 0 : Décidez si vous devez migrer

Rien n'oblige à la migration. Le post de lancement de Google indique que "Gemini 3.7 Flash reste entièrement pris en charge", et aucune date de fin de support n'est publiée. La tarification par jeton est inchangée, donc le seul coût supplémentaire est l'utilisation. Artificial Analysis a mesuré 3.8 Flash à un niveau de réflexion élevé utilisant environ 48 000 jetons de sortie par tâche sur leur index, soit 30 % de plus que 3.7 Flash, ce qui a fait passer le coût par tâche de 0,40 $ à 0,58 $ aux mêmes tarifs. Leur score d'index est passé de 56 à 59, et la précision de l'utilisation des outils sur τ³-Banking a augmenté de 12 points pour atteindre 45 %.

Le compromis est donc une plus grande capacité par tâche pour plus de jetons par tâche. Si votre charge de travail est courte, sensible à la latence, ou passe déjà ses évaluations sur 3.7 Flash, vous pouvez rester sur place. La comparaison complète 3.8 Flash vs 3.7 Flash contient une matrice de décision par charge de travail. Si vous migrez, continuez à lire.

Étape 1 : Échangez l'ID du modèle dans les deux formes

API Interactions (API principale de Google pour Gemini 3.x) :

{"model": "gemini-3.7-flash", "input": "..."}
{"model": "gemini-3.8-flash", "input": "..."}

generateContent héritée (toujours supportée, pas de fin de vie) :

POST /v1beta/models/gemini-3.7-flash:generateContent
POST /v1beta/models/gemini-3.8-flash:generateContent

SDK Python, les deux chemins :

client.interactions.create(model="gemini-3.8-flash", input=..., generation_config={"thinking_level": "medium"})
client.models.generate_content(model="gemini-3.8-flash", contents=..., config=types.GenerateContentConfig(thinking_config=types.ThinkingConfig(thinking_level="low")))

Si vous n'avez jamais utilisé l'API Interactions, le guide de l'API 3.8 Flash couvre les deux formes de bout en bout ; l'ancien tutoriel de l'API 3.7 Flash ne couvrait que generateContent, c'est pourquoi ce guide montre les deux.

La liste de contrôle de migration en neuf points

Parcourez-les dans l'ordre. Les éléments 1 à 4 sont des changements de configuration qui apparaissent immédiatement. Les éléments 5 et 6 affectent les boucles d'outils et l'état multi-tours. Les éléments 7 à 9 sont des changements de planification et de média que vous ne détecterez qu'en testant.

1. Mappez thinking_level: "minimal" à "low"

C'est celui qui casse en premier. 3.8 Flash accepte low, medium et high. L'envoi de minimal renvoie une erreur de validation. La valeur par défaut lorsque vous n'envoyez rien est medium. Gemini 3 Pro par défaut est high, ne copiez donc pas une configuration Pro en pensant qu'elle correspond.

Avant (3.7 Flash, Interactions) :

{"generation_config": {"thinking_level": "minimal"}}

Après (3.8 Flash) :

{"generation_config": {"thinking_level": "low"}}

Forme héritée, après :

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

La documentation sur la réflexion de Google décrit low comme le paramètre de latence et medium comme la valeur par défaut pour le code complexe et le travail d'agent. Quel niveau utiliser par itinéraire est un article à part entière ; à des fins de migration, low est le remplacement direct de minimal.

2. Supprimez temperature, top_p et top_k

Le conseil de Google pour chaque modèle Gemini 3 est de maintenir la température à sa valeur par défaut de 1.0. La baisser "peut provoquer des bouclages ou une dégradation des performances". De nombreuses configurations 3.7 Flash comportent un temperature: 0.2 hérité des générations précédentes. Supprimez les clés d'échantillonnage plutôt que de les définir.

Avant :

{"generationConfig": {"temperature": 0.2, "topP": 0.9, "topK": 40}}

Après :

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "medium"}}}

Si vous utilisiez une basse température pour obtenir du JSON reproductible, utilisez plutôt des sorties structurées. Elles sont prises en charge sur 3.8 Flash et vous donnent une réponse structurée par schéma sans toucher à l'échantillonnage.

3. Remplacez thinking_budget par thinking_level

thinking_budget était un plafond de jetons entier. thinking_level est une énumération de chaînes de caractères. Il n'y a pas de mappage arithmétique entre eux, alors choisissez le niveau en fonction de l'intention : les routes de latence obtiennent low, les routes par défaut obtiennent medium, les routes multi-étapes les plus difficiles obtiennent high.

Avant :

{"generationConfig": {"thinkingConfig": {"thinkingBudget": 4096}}}

Après :

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Les jetons de réflexion sont toujours facturés comme des jetons de sortie et rapportés dans usageMetadata.thoughtsTokenCount, donc le contrôle des coûts passe d'un plafond strict à un choix de niveau plus une assertion dans vos tests (voir la section de régression ci-dessous).

4. Supprimez candidate_count

Gemini 3 et les versions ultérieures ne prennent pas en charge plusieurs candidats. Supprimez la clé et tout code qui indexait candidates[1] ou au-delà.

Avant :

{"generationConfig": {"candidateCount": 2}}

Après :

{"generationConfig": {}}

Si vous échantillonniez plusieurs candidats pour choisir le meilleur, le remplacement sur 3.8 Flash est un niveau de réflexion plus élevé, qui effectue la vérification au sein d'une seule réponse.

5. Ajoutez call_id et name à chaque résultat de fonction

C'est le deuxième point de rupture difficile. Sur 3.8 Flash, chaque résultat de fonction que vous renvoyez doit porter à la fois l'id de l'appel et le name de la fonction. Le guide Gemini 3 de Google indique de "s'assurer que tous les objets FunctionResponse incluent call_id et name". Le code qui n'échoit que le nom échouera lors de l'étape de résultat de l'outil.

API Interactions, après :

{
  "previous_interaction_id": "<id de l'étape function_call>",
  "input": [{
    "type": "function_result",
    "name": "get_weather",
    "call_id": "<id de l'étape function_call>",
    "result": [{"type": "text", "text": "{\"temp_c\": 24}"}]
  }]
}

L'étape function_call du modèle vous donne id, name et arguments ; copiez les deux premiers tels quels. Dans la forme héritée, la partie functionResponse contient la même valeur dans un champ nommé id (correspondant à l'id de la partie functionCall du modèle) ainsi que name et response. La référence sur l'appel de fonction de Google contient les exemples canoniques, et le guide d'appel de fonction de 3.8 Flash explique la boucle complète en deux étapes, y compris pourquoi 3.8 Flash appelle les outils plus de fois par tâche que 3.7 Flash.

6. Renvoyez les signatures de pensée exactement telles que reçues

Les modèles Gemini 3 attachent des signatures de pensée aux parties de réponse. Lorsque vous construisez le tour suivant vous-même, renvoyez chaque partie inchangée, signatures incluses, pour tous les types de parties, pas seulement le texte. Supprimer ou re-sérialiser les dégrade la continuité du modèle à l'étape suivante.

L'API Interactions supprime ce travail lorsque vous laissez le serveur conserver l'état : passez previous_interaction_id et Google conserve l'historique. Si vous définissez store: false pour un appel sans état, vous possédez à nouveau l'historique et devez renvoyer vous-même les blocs de pensée et les signatures. Dans la version héritée generateContent, vous possédez toujours l'historique, alors vérifiez tout code qui reconstruit contents à partir d'une copie tronquée de la dernière réponse.

7. Allouez plus de jetons par route

Cet élément n'a pas d'erreur à détecter, c'est pourquoi il est souvent manqué. Le chiffre de +30 % de jetons de sortie de Artificial Analysis est une moyenne sur leur index à un niveau de réflexion élevé. La propre formulation de Google est que le modèle "peut utiliser plus de jetons sur des tâches plus longues et complexes, par conception" et que l'utilisation augmente "surtout à des niveaux d'effort plus élevés".

Planifiez par route, pas globalement :

• Points de terminaison sensibles à la latence : low. AA a mesuré 0,8 minute par tâche à faible contre 2,5 à élevé, et 0,24 $ par tâche contre 0,58 $.
• Routes par défaut : medium, à environ 0,41 $ par tâche sur le même index.
• Boucles d'agent : attendez-vous à plus de tours d'appel d'outil par tâche, donc plafonnez la boucle par nombre de tours, pas seulement par jetons.

Revoyez également le plafond de 65 536 jetons de sortie. Une invite 3.7 Flash qui renvoyait 40 000 jetons avec réflexion peut maintenant s'approcher de la limite. Si vous modélisez la facture, la ventilation des prix de 3.8 Flash calcule les chiffres par tâche aux trois niveaux.

8. Testez media_resolution_high sur les PDF par rapport à la vidéo

3.8 Flash accepte les entrées texte, image, vidéo, audio et PDF. Le paramètre de résolution média modifie le nombre de jetons que chaque entrée média consomme, et le coût diffère selon le type de média, de sorte que le même paramètre qui est bon marché sur une page PDF peut être coûteux sur une longue vidéo. Ne reprenez pas un paramètre de haute résolution global de 3.7 Flash sans mesurer. Envoyez un PDF représentatif et une vidéo représentative à chaque résolution et comparez le usageMetadata.promptTokenCount entre eux.

9. Supprimez tout appel de segmentation d'image

La segmentation d'image n'est pas prise en charge sur les modèles Gemini 3. Si un pipeline de l'ère 3.7 Flash acheminait toujours la segmentation via un ancien modèle Gemini, ce chemin est distinct de cette migration ; si une invite demandait à 3.8 Flash des masques de segmentation, attendez-vous à ce qu'elle échoue plutôt que de renvoyer une sortie utilisable. La génération d'images, la génération audio et l'API Live ne sont pas non plus prises en charge sur 3.8 Flash, selon la page du modèle.

Construire le plan de régression dans Apidog

Une migration avec deux changements majeurs et un décalage d'utilisation des jetons nécessite une comparaison reproductible, pas un simple curl ponctuel. Voici la configuration que nous utilisons dans Apidog, qui fonctionne parce qu'Apidog est un client API et un exécuteur de tests : il envoie les requêtes, vérifie les réponses et planifie l'exécution. Il n'exécute pas le modèle.

Environnement et variables. Créez un environnement Gemini avec GEMINI_API_KEY stockée comme variable secrète et une variable MODEL. Utilisez {{MODEL}} dans l'URL de la requête generateContent et dans le champ model de la requête Interactions, afin que la même requête enregistrée s'exécute sur l'un ou l'autre modèle.

Invites de référence (golden prompts). Enregistrez 10 à 20 invites qui représentent vos routes réelles : un court échange de chat, une extraction de sortie structurée, un appel de fonction en deux tours avec un outil simulé, une entrée PDF et une entrée vidéo. Chacune est une requête dans un scénario de test.

Assertions. Ajoutez-en trois par requête :

• Le statut est 200, et le corps de la réponse correspond à un schéma JSON. Pour les routes de sortie structurées, faites une assertion sur les champs que vous analysez en aval.
• usageMetadata.thoughtsTokenCount reste sous un plafond que vous définissez par route (par exemple, 8 000 sur une route low). C'est la garde qui détecte une configuration qui est silencieusement revenue à medium.
• usageMetadata.totalTokenCount reste sous le budget de la route de l'élément 7.

Cote à cote. Dupliquez le scénario, définissez MODEL sur gemini-3.7-flash dans l'un et sur gemini-3.8-flash dans l'autre, et exécutez les deux. Les rapports de test d'Apidog affichent la réussite/l'échec par assertion et les corps de réponse, de sorte que le delta de jetons par invite est visible dans une seule vue plutôt que reconstruit à partir des journaux. Pour le scénario d'appel de fonction, ajoutez une assertion selon laquelle l'call_id que vous avez renvoyé est égal à l'id de l'function_call de l'étape précédente.

Planifiez-le. Transformez le scénario 3.8 Flash en une exécution planifiée afin que les plafonds de jetons soient vérifiés quotidiennement pendant la fenêtre de déploiement. Le guide des tests API planifiés couvre la configuration. Si vous préférez suivre dans l'application, Téléchargez Apidog et importez les fragments curl ci-dessus.

Retour arrière : Garder 3.7 Flash derrière un drapeau de configuration

Parce que 3.7 Flash reste entièrement pris en charge et partage le prix de 3.8 Flash, le retour arrière est peu coûteux : conservez l'ID du modèle dans la configuration plutôt que dans le code.

{"gemini_model": "gemini-3.8-flash", "gemini_fallback_model": "gemini-3.7-flash"}

Trois règles rendent le drapeau sûr :

• Maintenez la forme de requête migrée sur les deux modèles. Les éléments 1 à 6 (pas de minimal, pas de clés d'échantillonnage, thinking_level et non thinking_budget, pas de candidate_count, call_id + name, signatures conservées) sont également valides sur 3.7 Flash, donc un drapeau basculé n'a jamais besoin d'un second chemin de code.
• Déployez par route. Activez d'abord les routes de latence de faible niveau, car leur delta de jetons est le plus petit ; activez les boucles d'agent en dernier, après que le scénario côte à côte ait réussi pendant quelques jours.
• Surveillez les jetons, pas seulement les erreurs. Un déclencheur de retour arrière sur 3.8 Flash est plus susceptible d'être une régression de coût ou de latence qu'une erreur 4xx, alors intégrez les assertions de plafond de jetons dans votre système d'alerte.

FAQ

Est-ce que Gemini 3.8 Flash coûte plus cher que 3.7 Flash ? Pas par jeton. Les deux sont à 0,75 $ en entrée / 3,75 $ en sortie par million jusqu'au 31 décembre 2026, et les deux passeront à 1,50 $ / 7,50 $ le 1er janvier 2027. Par tâche, 3.8 Flash utilise plus de jetons par conception ; Artificial Analysis a mesuré environ 30 % de jetons de sortie en plus sur leur index à un niveau de réflexion élevé.

Que se passe-t-il si je laisse thinking_level: "minimal" en place ? La requête échoue avec une erreur de validation sur 3.8 Flash. Remplacez-la par low. Le guide des niveaux de réflexion explique ce que fait chaque niveau restant et comment mesurer la différence.

Dois-je migrer vers l'API Interactions pour utiliser 3.8 Flash ? Non. generateContent est décrit comme hérité mais reste entièrement pris en charge sans date de fin de vie, et 3.8 Flash fonctionne avec. L'API Interactions ajoute un état de conversation côté serveur via previous_interaction_id, ce qui supprime la gestion des signatures de pensée de l'élément 6.

Est-ce que 3.7 Flash est déprécié ? Google affirme qu'il "reste entièrement pris en charge" et n'a pas publié de date de dépréciation. C'est ce qui rend le retour arrière via un drapeau de configuration viable.

Puis-je conserver la même température que j'ai réglée pour 3.7 Flash ? Le conseil de Google pour tous les modèles Gemini 3 est de laisser la température à 1.0. Si vous la modifiiez déjà sur 3.7 Flash, cette migration est le moment de la supprimer et de vérifier vos évaluations ; les sorties structurées sont le chemin pris en charge pour les formes déterministes.

Déployez-le par étapes

La migration elle-même est minime : un changement d'ID, quatre suppressions ou renommages de configuration, deux champs de boucle d'outils et une vérification des signatures. La partie qui prend du temps est de prouver que le budget de jetons est respecté par route, et c'est un problème de test. Enregistrez les invites de référence, faites des assertions sur le schéma et les plafonds de jetons, exécutez 3.7 et 3.8 Flash côte à côte jusqu'à ce que les chiffres se stabilisent, puis basculez le drapeau une route à la fois. Si une route régresse, le drapeau la renvoie à 3.7 Flash sans modification de code, et vous conservez les routes améliorées.