Premier appel à l’API Gemini en Python avec le SDK google-genai

📍 Guide principal : Développer avec l’API Google Gemini — pour la vue d’ensemble des modèles et de l’écosystème, lisez-le d’abord.

Tout part d’un premier appel qui fonctionne. Avant de parler de function calling, de multimodal ou de RAG, il faut un script Python qui envoie une instruction à Gemini et affiche sa réponse — sans erreur d’authentification, sans paquet obsolète, sans clé exposée. C’est précisément ce que ce tutoriel met en place, du compte vierge jusqu’à une petite conversation en console.

Ce que vous allez apprendre

• Obtenir une clé API Gemini gratuite depuis Google AI Studio et la stocker proprement.
• Installer le SDK officiel google-genai dans un environnement Python isolé.
• Générer du texte avec generate_content et lire la réponse.
• Donner un rôle au modèle avec une instruction système et régler la température.
• Afficher la réponse au fil de l’eau grâce au streaming.
• Tenir une conversation à plusieurs tours qui garde le contexte.

Ce que vous allez construire

Un petit assistant en ligne de commande : vous tapez une question, il répond. À la fin, il aura une personnalité fixée par une instruction système, affichera ses réponses progressivement comme une vraie interface de chat, et se souviendra de ce que vous avez dit plus tôt dans la session. Une centaine de lignes de Python, mais toutes les fondations de l’API y passent.

Prérequis

• Python 3.10 ou plus récent installé (python --version pour vérifier).
• Un compte Google (le même que pour Gmail convient).
• Des notions de base en Python : variables, fonctions, boucle while.
• ⏱️ Temps estimé : environ 25 minutes.

Test express : si vous savez créer un fichier .py et l’exécuter avec python mon_fichier.py, vous êtes prêt. Sinon, familiarisez-vous d’abord avec l’exécution d’un script Python.

Étape 1 — Obtenir une clé API dans Google AI Studio

La clé API est le mot de passe qui autorise votre code à parler aux modèles. On l’obtient gratuitement, en une minute, dans Google AI Studio — la console qui sert aussi à tester les modèles dans le navigateur.

Rendez-vous sur aistudio.google.com, connectez-vous avec votre compte Google, puis ouvrez la section « API keys » (clés API). Cliquez sur « Create API key » (créer une clé). AI Studio génère une chaîne d’une quarantaine de caractères : c’est votre clé. Copiez-la immédiatement dans un endroit sûr.

Un point de vigilance dès maintenant : cette clé engage potentiellement une facturation et donne accès aux modèles en votre nom. Elle ne doit jamais finir dans votre code source, ni sur un dépôt public, ni dans une capture d’écran. Nous la rangerons à l’étape suivante dans une variable d’environnement, à l’écart du code.

✅ Point d’étape — Vous devez avoir une chaîne de caractères copiée quelque part de temporaire. Si AI Studio refuse de créer la clé, vérifiez que vous avez bien accepté les conditions d’utilisation affichées à la première connexion.

Étape 2 — Isoler l’environnement et installer le SDK

On ne mélange jamais les dépendances d’un projet avec celles du système. Un environnement virtuel crée un Python propre, dédié à ce projet, qu’on peut supprimer sans rien casser ailleurs. On y installe ensuite le seul paquet dont on a besoin.

# Creer un dossier de projet et s'y placer
mkdir assistant-gemini
cd assistant-gemini

# Creer puis activer un environnement virtuel
python -m venv .venv
# Sur Linux ou macOS :
source .venv/bin/activate
# Sur Windows (PowerShell) :
.venv\Scripts\Activate.ps1

# Installer le SDK officiel
pip install google-genai

Après l’activation, votre invite de commande affiche (.venv) au début de la ligne : c’est le signal que vous travaillez bien dans l’environnement isolé. La commande pip install google-genai télécharge le SDK et ses dépendances. Attention au nom exact : c’est google-genai, le SDK unifié actuel — pas l’ancien google-generativeai, qui appartient à une génération précédente et que vous croiserez encore dans de vieux tutoriels.

Pour gérer la clé sans la coder en dur, installez aussi un petit utilitaire qui lit les fichiers .env :

pip install python-dotenv

Créez maintenant un fichier nommé .env à la racine du projet, avec une seule ligne — collez votre vraie clé à la place du texte d’exemple :

GEMINI_API_KEY=collez_votre_cle_ici

Et créez un fichier .gitignore contenant .env et .venv/, pour qu’aucun de ces éléments ne parte jamais sur un dépôt Git. Cette précaution de trente secondes évite la fuite de clé la plus courante.

✅ Point d’étape — pip list doit faire apparaître google-genai. Votre dossier contient .env, .gitignore et .venv/.

Étape 3 — Le premier appel

On a tout pour un premier échange. Le SDK fonctionne autour d’un objet client qui porte l’authentification, et d’un appel à generate_content qui prend un modèle et un contenu. Créez un fichier premier_appel.py :

from dotenv import load_dotenv
from google import genai

# Charge la cle depuis le fichier .env vers les variables d'environnement
load_dotenv()

# Le client lit automatiquement GEMINI_API_KEY
client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explique en trois phrases ce qu'est une API, pour un debutant.",
)

print(response.text)

Exécutez avec python premier_appel.py. Après une ou deux secondes, trois phrases d’explication s’affichent dans votre terminal. Si c’est le cas, l’essentiel est acquis : l’authentification passe, le modèle répond, et vous lisez le texte via response.text. Notez qu’on n’a jamais écrit la clé dans le code : load_dotenv() l’a chargée depuis .env, et le client l’a trouvée tout seul dans GEMINI_API_KEY.

Le choix du modèle mérite un mot. gemini-2.5-flash est le bon réglage par défaut : rapide, économique, assez intelligent pour la grande majorité des tâches. On ne change que si un besoin précis le justifie.

Au-delà du texte, la réponse transporte des métadonnées utiles. response.usage_metadata indique combien de jetons votre requête a consommés — en entrée, en sortie et au total. Ajoutez temporairement print(response.usage_metadata) après l’appel : vous verrez les compteurs prompt_token_count, candidates_token_count et total_token_count. Prendre l’habitude de regarder ces chiffres dès le début installe le bon réflexe d’ingénieur : la facturation se fait au jeton, et savoir ce que coûte chaque appel évite les surprises une fois en production.

✅ Point d’étape — Vous voyez une réponse en français dans le terminal. En cas d’erreur « API key not valid », relisez votre .env : pas d’espaces autour du signe égal, pas de guillemets autour de la clé.

Étape 4 — Donner un rôle au modèle

Par défaut, Gemini répond de façon neutre. Pour une application, on veut généralement fixer un comportement : un ton, une langue, des contraintes. C’est le rôle de l’instruction système, qui s’applique à toute la session sans qu’on la répète à chaque message. On la passe dans un objet de configuration, aux côtés d’autres réglages comme la température.

from dotenv import load_dotenv
from google import genai
from google.genai import types

load_dotenv()
client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="J'ai un site lent, par ou commencer ?",
    config=types.GenerateContentConfig(
        system_instruction=(
            "Tu es un mentor en developpement web. Tu reponds en francais, "
            "de maniere concise, avec des etapes concretes et numerotees."
        ),
        temperature=0.4,
        max_output_tokens=400,
    ),
)

print(response.text)

Trois réglages entrent en jeu ici. L’instruction système installe la posture de mentor pour tout l’échange. La temperature à 0,4 garde les réponses factuelles et reproductibles ; on la monterait vers 0,9 pour de la rédaction créative. Enfin, max_output_tokens borne la longueur de la réponse : un garde-fou direct contre les coûts et les pavés à rallonge. Relancez le script : la réponse est désormais structurée en étapes numérotées, dans le ton demandé.

✅ Point d’étape — La réponse reflète l’instruction système (étapes numérotées, ton de mentor). Si elle l’ignore, vérifiez que system_instruction est bien à l’intérieur de types.GenerateContentConfig, et non passé comme un contenu.

Étape 5 — Afficher la réponse au fil de l’eau

Sur une réponse longue, attendre plusieurs secondes l’écran figé donne une impression de lenteur. Le streaming résout cela : le modèle renvoie sa réponse par fragments, qu’on affiche dès leur arrivée. La méthode change à peine — generate_content_stream au lieu de generate_content — et on itère sur les fragments.

from dotenv import load_dotenv
from google import genai

load_dotenv()
client = genai.Client()

flux = client.models.generate_content_stream(
    model="gemini-2.5-flash",
    contents="Raconte en un paragraphe l'histoire de l'invention du telephone.",
)

for fragment in flux:
    print(fragment.text, end="", flush=True)
print()  # saut de ligne final

À l’exécution, le texte s’écrit progressivement, mot après mot, comme dans une interface de chat moderne. Chaque fragment porte un bout de texte dans fragment.text ; l’option end="" évite les retours à la ligne intempestifs, et flush=True force l’affichage immédiat sans attendre que le tampon se remplisse. C’est exactement ce mécanisme que le tutoriel sur le chatbot Node.js exploitera côté serveur.

✅ Point d’étape — Le texte apparaît graduellement et non d’un bloc. Sinon, vérifiez que vous appelez bien generate_content_stream et non generate_content.

Étape 6 — Tenir une conversation

Un appel isolé n’a pas de mémoire : si vous renvoyez « et en moins cher ? », le modèle ignore de quoi vous parliez. Pour une vraie conversation, le SDK fournit un objet chat qui conserve l’historique des tours et le renvoie automatiquement au modèle à chaque message.

from dotenv import load_dotenv
from google import genai

load_dotenv()
client = genai.Client()

chat = client.chats.create(model="gemini-2.5-flash")

print("Assistant pret. Tapez 'quit' pour sortir.\n")
while True:
    question = input("Vous : ")
    if question.strip().lower() in ("quit", "exit"):
        break
    reponse = chat.send_message(question)
    print("Assistant :", reponse.text, "\n")

On crée le chat une fois avec client.chats.create, puis chaque chat.send_message ajoute votre message à l’historique et renvoie la réponse. Essayez un enchaînement : « Donne-moi une idée de projet Python pour débutant », puis « Détaille le premier point ». Le modèle comprend que « le premier point » renvoie à sa réponse précédente — preuve que le contexte est bien conservé. C’est l’objet chat qui gère cette liste de messages pour vous ; sans lui, il faudrait reconstruire l’historique à la main à chaque tour.

✅ Point d’étape — Le second échange tient compte du premier. La boucle se quitte proprement avec quit.

Un point à garder en tête pour plus tard : à chaque tour, l’objet chat renvoie au modèle tout l’historique accumulé. Une conversation qui s’allonge consomme donc de plus en plus de jetons à chaque message, puisque le contexte grossit. Pour un assistant à sessions courtes, c’est sans conséquence ; pour un service qui tient de longues conversations, on apprend vite à tronquer ou résumer l’historique ancien afin de maîtriser le coût. Le SDK n’impose rien là-dessus : la décision vous revient, et elle commence par avoir conscience du phénomène.

Étape 7 — Vérifier le tout

Vous disposez maintenant de toutes les briques de base : authentification par variable d’environnement, génération, instruction système, streaming et conversation. Un dernier contrôle consiste à combiner instruction système et streaming dans la boucle de conversation — un assistant qui a un rôle et répond au fil de l’eau. Le passage de send_message à send_message_stream suffit, et l’instruction système se fixe à la création du chat via le même objet de configuration que vu plus haut. C’est l’exercice « à vous de jouer » ci-dessous.

🐞 Pièges fréquents

✅ Récapitulatif

Vous êtes parti d’un compte vierge et vous avez un assistant en console fonctionnel. En chemin, vous avez acquis les gestes fondateurs de l’API Gemini : créer un client authentifié sans exposer la clé, générer du texte avec generate_content, façonner le comportement du modèle par une instruction système et la température, fluidifier l’affichage avec le streaming, et conserver le contexte d’une conversation avec l’objet chat. Toutes les capacités plus avancées de cette série — fonctions, multimodal, JSON structuré, RAG — se branchent sur ce même socle.

🧾 Aide-mémoire

💪 À vous de jouer

Reprenez la boucle de conversation de l’étape 6 et améliorez-la sur deux points : donnez à l’assistant une instruction système (par exemple « professeur de mathématiques patient »), et faites-le répondre en streaming pour un affichage progressif.

from dotenv import load_dotenv
from google import genai
from google.genai import types

load_dotenv()
client = genai.Client()

chat = client.chats.create(
    model="gemini-2.5-flash",
    config=types.GenerateContentConfig(
        system_instruction="Tu es un professeur de mathematiques patient. Tu reponds en francais.",
    ),
)

print("Professeur pret. Tapez 'quit' pour sortir.\n")
while True:
    question = input("Vous : ")
    if question.strip().lower() in ("quit", "exit"):
        break
    print("Professeur : ", end="", flush=True)
    for fragment in chat.send_message_stream(question):
        print(fragment.text, end="", flush=True)
    print("\n")

Tutoriels suivants

• Function calling : connecter Gemini à vos fonctions — la suite logique pour que l’assistant agisse, pas seulement parle.
• Sorties structurées JSON — obtenir des réponses exploitables directement par votre code.

Pour aller plus loin

🔝 Retour au guide principal de l’API Gemini. La documentation officielle ai.google.dev détaille tous les paramètres de génération.

Questions fréquentes

Dois-je payer pour exécuter ce tutoriel ? Non, le palier gratuit d’AI Studio suffit largement pour ces quelques appels.

Pourquoi un environnement virtuel ? Pour isoler les dépendances du projet et éviter les conflits avec d’autres installations Python sur votre machine.

Puis-je faire la même chose en JavaScript ? Oui, avec le paquet @google/genai et la méthode ai.models.generateContent ; la logique est identique. Le tutoriel chatbot Node.js le montre.

Comment changer de modèle ? Il suffit de remplacer la valeur de model, par exemple par gemini-2.5-pro pour un raisonnement plus poussé, au prix d’une latence et d’un coût supérieurs.