Comment utiliser l'API Gemini 3.8 Flash : API d'interactions, niveaux de réflexion et votre premier appel dans Apidog

Google a lancé Gemini 3.8 Flash le 2 septembre 2026, et l'ID du modèle API est la chaîne de caractères simple gemini-3.8-flash, sans suffixe de préversion. Il conserve le prix de lancement de 3.7 Flash de 0,75 $ par million de jetons d'entrée et 3,75 $ par million de jetons de sortie jusqu'au 31 décembre 2026. Google le décrit comme un modèle qui « travaille plus dur » : il effectue plus d'étapes de raisonnement et appelle plus souvent des outils sur des tâches complexes, ce qui se reflète sur votre facture de jetons.

Ce guide couvre le chemin complet vers une intégration fonctionnelle : obtenir une clé dans AI Studio, envoyer une première requête via l'API Interactions (la principale API de Google pour Gemini 3.x désormais), l'équivalent hérité generateContent que la plupart des codes existants utilisent encore, où thinking_level se situe dans chacun, le streaming, et comment lire thoughtsTokenCount afin que le coût de la réflexion ne vous surprenne jamais. Chaque appel est un simple HTTP avec JSON, vous pouvez donc construire et vérifier chacun d'eux dans Apidog avant de l'intégrer à votre code d'application.

Pour un aperçu du modèle, les benchmarks et ce qui a changé, commencez par ce qu'est Gemini 3.8 Flash. Le billet de blog de Google présente le cadre officiel.

API Gemini 3.8 Flash en un coup d'œil

Deux détails ressortent avant d'écrire du code. Le niveau de réflexion par défaut est medium, et non high comme sur Gemini 3 Pro. Et les jetons de réflexion sont facturés au tarif de sortie sur la page de tarification officielle, de sorte que le niveau que vous choisissez est une décision de coût autant qu'une décision de qualité. La ventilation des prix détaille les chiffres par tâche.

Étape 1 : Obtenir une clé API dans AI Studio

Ouvrez Google AI Studio, connectez-vous avec un compte Google et créez une clé API depuis la page des clés. La clé fonctionne immédiatement sur le niveau gratuit, avec des limites de débit et l'avertissement que Google indique que les données du niveau gratuit sont « utilisées pour améliorer nos produits ». Associez un compte de facturation pour passer au niveau 1 et bénéficier des limites de production.

Exportez la clé au lieu de la coller dans le code :

export GEMINI_API_KEY="AIza..."

Le SDK Python officiel lit GEMINI_API_KEY depuis l'environnement, donc genai.Client() n'a pas besoin d'arguments. Installez-le avec pip install google-genai.

Étape 2 : Votre premier appel avec l'API Interactions

Google considère désormais l'API Interactions comme le moyen principal d'appeler les modèles Gemini 3.x. La requête est un objet JSON unique : le modèle, une input et une generation_config facultative où réside thinking_level.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain HTTP caching in 3 sentences.",
    "generation_config": {"thinking_level": "medium"}
  }'

La réponse est une liste d'étapes d'exécution au lieu d'un message unique. Les réflexions du modèle et les appels d'outils apparaissent comme des étapes, et la dernière étape est model_output, qui contient le texte. En Python, le SDK aplatit cela pour vous :

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain HTTP caching in 3 sentences.",
    generation_config={"thinking_level": "medium"},
)

print(interaction.output_text)

Laissez temperature, top_p et top_k de côté. Les conseils de Google pour chaque modèle Gemini 3 sont de maintenir la température à sa valeur par défaut de 1.0, car la réduire « peut provoquer des boucles ou une dégradation des performances ». Si vous avez copié une configuration d'un modèle plus ancien, c'est la première ligne à supprimer.

Étape 3 : Conversation multi-tours avec previous_interaction_id

L'API Interactions maintient l'état de la conversation côté serveur par défaut. Pour continuer une conversation, envoyez l'id de la réponse précédente comme previous_interaction_id avec uniquement la nouvelle entrée de l'utilisateur. Vous ne renvoyez pas l'historique.

follow_up = client.interactions.create(
    model="gemini-3.8-flash",
    input="Now give one example of a Cache-Control header.",
    previous_interaction_id=interaction.id,
)
print(follow_up.output_text)

Si vos règles de conformité interdisent le stockage côté serveur, définissez store: false. L'inconvénient est que vous gérez alors vous-même l'état, y compris le renvoi des blocs de réflexion et des signatures de pensée du modèle exactement comme vous les avez reçus à chaque tour. C'est la même règle qui complique l'utilisation des outils, couverte dans le guide d'appel de fonctions pour 3.8 Flash.

Étape 4 : Le chemin generateContent hérité

La plupart du code Gemini en production appelle encore generateContent. Google le qualifie d'hérité, mais il « reste entièrement pris en charge » sans date de fin de vie, vous n'avez donc rien à réécrire aujourd'hui. Notre guide de l'API Gemini 3.7 Flash ne couvrait que ce chemin ; la forme est identique pour 3.8 Flash, et le paramètre de réflexion se trouve à un endroit différent de celui des Interactions.

Dans generateContent, le niveau se trouve sous generationConfig.thinkingConfig.thinkingLevel, en camelCase :

curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Explain HTTP caching in 3 sentences."}]}],
    "generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}
  }'

L'équivalent Python utilise des objets de configuration typés :

from google import genai
from google.genai import types

client = genai.Client()

response = client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Explain HTTP caching in 3 sentences.",
    config=types.GenerateContentConfig(
        thinking_config=types.ThinkingConfig(thinking_level="low")
    ),
)
print(response.text)

Si vous utilisiez auparavant une configuration avec thinking_budget comme entier, remplacez-le par l'énumération de chaînes de caractères. candidate_count est également absent sur Gemini 3 et versions ultérieures. La liste de contrôle complète, avec le JSON avant et après pour chaque changement, se trouve dans le guide de migration de 3.7 à 3.8 Flash.

Voici le même ensemble de préoccupations côte à côte, afin que vous puissiez traduire entre les deux API sans relire les deux documentations :

Étape 5 : Streaming et lecture du coût de la réflexion

Pour les interfaces de chat, remplacez le nom de la méthode par streamGenerateContent et ajoutez ?alt=sse pour obtenir des événements envoyés par le serveur (SSE), un fragment partiel de candidates par événement :

curl -N "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"List three HTTP caching headers."}]}]}'

En streaming ou non, chaque réponse generateContent se termine par un objet usageMetadata. Lisez-le à chaque appel :

"usageMetadata": {
  "promptTokenCount": 12,
  "candidatesTokenCount": 84,
  "thoughtsTokenCount": 310,
  "totalTokenCount": 406
}

thoughtsTokenCount est le nombre à surveiller sur 3.8 Flash. Les jetons de réflexion sont facturés comme des jetons de sortie à 3,75 $ par million pendant la période de lancement, et Google indique que le modèle « pourrait utiliser plus de jetons pour maximiser les performances, en particulier à des niveaux d'effort plus élevés ». Artificial Analysis a mesuré environ 48 000 jetons de sortie par tâche lors de son exécution d'index à high, soit 30 % de plus que 3.7 Flash, ce qui a fait passer le coût par tâche de 0,40 $ à 0,58 $ à des prix par jeton inchangés. Leurs exécutions à medium et low ont donné 0,41 $ et 0,24 $ par tâche. Le guide des niveaux de réflexion transforme ces chiffres en une stratégie par route.

Pour voir ce que le modèle a raisonné, ajoutez "includeThoughts": true à l'intérieur de thinkingConfig. Les résumés de réflexion reviennent sous forme de parties signalées par "thought": true ; ignorez-les lorsque vous assemblez la réponse visible.

Erreurs que vous rencontrerez la première heure

• thinking_level: "minimal" échoue à la validation. Gemini 3.8 Flash ne prend en charge que low, medium et high. L'envoi de minimal renvoie une erreur 400 INVALID_ARGUMENT avec le message « Thinking level MINIMAL is not supported for this model. Please retry with other thinking level. » (vérifié avec un appel en direct le 3 septembre 2026), et la solution est de changer un mot pour low. Les anciennes configurations 3.x et les extraits copiés sont la source habituelle.
• Un code 429 signifie que vous avez atteint la limite de votre niveau, pas un bug. La page des limites de débit explique les niveaux : le niveau gratuit est soumis à des limites de débit, le niveau 1 est débloqué lorsque vous associez un compte de facturation, le niveau 2 nécessite 100 $ de dépenses plus trois jours, et le niveau 3 nécessite 1 000 $ plus 30 jours. Les chiffres de requêtes par minute et de jetons par minute par modèle ne sont affichés que sur la page des limites de débit d'AI Studio pour votre compte, alors vérifiez-les plutôt que de vous fier à un chiffre provenant d'un billet de blog. En cas de 429, attendez et réessayez ; en cas de 429 répétés à faible volume, mettez à niveau le niveau. Pour les tâches hors ligne, l'API Batch est la meilleure solution : elle fonctionne à 50 % de réduction (0,375 $ / 1,875 $ par million de jetons pendant la période de lancement) et a ses propres limites de jetons en file d'attente de 3 millions au niveau 1, 400 millions au niveau 2 et 1 milliard au niveau 3. Le guide du mode batch de Gemini montre la forme de la requête.
• `call_id` manquant sur un résultat de fonction. Si vous utilisez des outils, chaque function_result (Interactions) doit comporter à la fois call_id et name sur 3.8 Flash, et chaque functionResponse héritée doit comporter l'id correspondant plus name. L'omission de l'un ou l'autre fait échouer le tour.

Testez les deux endpoints dans Apidog avant leur déploiement

Une fois que les deux requêtes fonctionnent depuis le terminal, déplacez-les dans un endroit où toute l'équipe peut les exécuter. Téléchargez Apidog, créez un projet et ajoutez les deux endpoints ci-dessus comme requêtes enregistrées. Quatre habitudes sont payantes :

• Gardez la clé en dehors de la requête. Ajoutez GEMINI_API_KEY comme variable d'environnement et référencez-la comme {{GEMINI_API_KEY}} dans l'en-tête x-goog-api-key. La requête enregistrée ne contient jamais le secret, et passer d'une clé de niveau gratuit à une clé facturée est un seul changement d'environnement.
• Vérifiez l'état et l'utilisation des jetons. Ajoutez une assertion selon laquelle l'état est 200, puis une assertion de chemin JSON selon laquelle usageMetadata.thoughtsTokenCount reste sous un plafond que vous choisissez par invite. Le plafond est votre alarme de régression des coûts : si une mise à jour d'invite ou un changement silencieux du modèle fait augmenter les jetons de réflexion, le test échoue avant que la facture ne le fasse. Le guide de test SSE couvre la variante de streaming, qu'Apidog affiche comme un flux d'événements fusionné au lieu de fragments bruts.
• Envoyez la même invite aux trois niveaux. Dupliquez la requête avec low, medium et high, et comparez thoughtsTokenCount et le temps de réponse côte à côte. Cela vous donne des chiffres réels pour vos invites au lieu de moyennes d'index.
• Planifiez-le. Transformez les requêtes en scénario de test et exécutez-les selon un calendrier, afin qu'un changement de limite de débit, un changement de validation comme la suppression de minimal, ou un pic de jetons apparaisse dans un rapport, et non en production. Comment planifier des tests d'API dans Apidog décrit la configuration.

Apidog n'exécute pas le modèle et ne remplace pas le SDK. Il vous fournit une version enregistrée, partageable et vérifiable des appels HTTP, ce qui est la partie que la plupart des équipes ignorent jusqu'à ce que quelque chose se casse.

FAQ

• Quel endpoint les nouveaux projets devraient-ils utiliser ? L'API Interactions. Google qualifie generateContent d'hérité, et il est toujours entièrement pris en charge, mais les nouvelles fonctionnalités arrivent d'abord sur Interactions et l'état côté serveur rend le code multi-tours plus concis. Gardez generateContent pour les services existants jusqu'à ce que vous ayez une raison de migrer.
• Ai-je besoin d'un compte payant pour appeler Gemini 3.8 Flash ? Non. Une clé AI Studio gratuite fonctionne, avec des limites de débit et les conditions d'utilisation des données de Google. Le guide d'utilisation gratuite liste ce que le niveau gratuit vous donnera et ne vous donnera pas, y compris le fait que l'application Gemini nécessite un plan AI Pro ou Ultra pour 3.8 Flash.
• Est-ce que 3.8 Flash est plus lent que 3.7 Flash ? Par jeton, non. Logan Kilpatrick de Google a déclaré qu'il était à peu près à la même vitesse, et Artificial Analysis a mesuré environ 300 jetons de sortie par seconde. Par tâche, il prend plus de temps à high (2,5 minutes contre 2,2 dans leurs tests) car il génère plus de jetons.
• Puis-je continuer à appeler Gemini 3.7 Flash ? Oui. Google déclare que 3.7 Flash « reste entièrement pris en charge » et n'a pas publié de date de dépréciation. Si les dépenses supplémentaires en jetons sur 3.8 Flash ne vous apportent rien pour votre charge de travail, rester en place est un choix valable.
• Est-ce que 3.8 Flash prend en charge l'API Live ou la génération d'images ? Non. Il ne produit que du texte. La génération audio, la génération d'images et l'API Live ne sont pas prises en charge sur ce modèle.

Pour aller plus loin

Vous disposez maintenant de deux chemins d'appel fonctionnels, d'un modèle multi-tours et d'une vérification de l'utilisation des jetons. À partir de là, configurez les outils avec le guide d'appel de fonctions, décidez de vos niveaux par route avec le billet sur les niveaux de réflexion, et si vous hésitez encore à passer à l'action, la comparaison entre 3.8 et 3.7 Flash expose les compromis. Laissez le scénario Apidog s'exécuter afin que la dérive des coûts se manifeste comme un test échoué.