+190 XP

L'API Gemini : vos premiers vrais appels

Voici un appel Gemini multimodal complet en Python : une image, une question, une réponse, chaque élément jouant un rôle propre à Gemini.

python
from google import genai

client = genai.Client()  # lit GEMINI_API_KEY depuis l'environnement

with open("invoice.png", "rb") as f:
    image_bytes = f.read()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=[
        {"text": "Extract the total amount and due date. Reply as JSON."},
        {"inline_data": {"mime_type": "image/png", "data": image_bytes}},
    ],
)

print(response.text)

C'est tout. Pas de manipulation en base64, pas d'endpoint vision séparé, pas de préprocesseur OCR. Vous donnez au modèle des octets et du texte ensemble, et il lit les deux. La suite de cette leçon détaille ce qui est propre à Gemini ici, car c'est là que se trouve la valeur.

Le SDK et le client

Le package est google-genai, le SDK Google GenAI unifié. Installez-le avec pip install google-genai. C'est le SDK actuel. Si vous tombez sur d'anciens tutoriels qui importent google.generativeai, il s'agit de la bibliothèque historique. Utilisez la nouvelle.

bash
pip install google-genai
export GEMINI_API_KEY="your-key-from-aistudio"

Récupérez la clé sur aistudio.google.com via « Get API key ». Le constructeur `genai.Client()` lit `GEMINI_API_KEY` automatiquement, vous la passez donc rarement dans le code. La référence complète se trouve sur ai.google.dev.

Un seul SDK dialogue avec deux backends. Le même client fonctionne avec la Gemini Developer API (la clé AI Studio, démarrage rapide) ou avec Vertex AI (Google Cloud, avec IAM, contrôles VPC et facturation entreprise). Vous basculez en définissant vertexai=True ainsi qu'un projet et une région. Vous ne réécrivez pas votre code. Prototypez sur la Developer API, puis passez à Vertex quand vous avez besoin de gouvernance. Nous traitons cette transition plus loin dans ce parcours.

Choisir le modèle : flash ou pro

La chaîne model est une vraie décision. La génération actuelle est Gemini 3, déclinée en plusieurs niveaux :

  • Flash est le cheval de trait. Rapide et peu coûteux, il gère bien l'extraction, la classification, le chat et les traitements à fort volume. La tâche de facture ci-dessus relève de Flash.
  • Pro est le modèle de raisonnement, pour les problèmes multi-étapes plus difficiles, le code dense et les longues chaînes analytiques. Il est plus lent et plus cher au token.
  • Les variantes Flash-Lite couvrent les cas au plus fort volume et au coût le plus bas.

Les identifiants de modèle changent souvent. Certains sortent avec un suffixe -preview, passent ensuite à un identifiant stable, et les anciennes générations (Gemini 2.5 et antérieures) reçoivent des dates de dépréciation. Consultez la liste à jour sur la page des modèles avant de mettre en production, et figez l'identifiant exact que vous avez testé plutôt qu'un alias flottant « latest ». Le principe reste valable à mesure que les numéros de version augmentent : partez sur Flash, ne passez à Pro que lorsque Flash peine visiblement.

Pourquoi c'est plus important sur Gemini

Gemini est nativement multimodal. Texte, images, audio, vidéo et PDF passent par le même modèle, et non par un module vision greffé après coup. L'arbitrage coût/latence entre Flash et Pro s'applique donc aussi au travail sur images et documents. Un modèle Flash qui lit un PDF de 40 pages suffit souvent.

La structure contents

contents est une liste de parts. Chaque part est un fragment d'entrée : une part text, une part inline_data (octets bruts plus un type MIME) ou une référence à un fichier uploadé. Le modèle les voit dans l'ordre, la position compte donc. Pour les tâches du type « fais X sur cet élément », placer l'instruction avant l'image, comme ci-dessus, fonctionne généralement bien.

Pour les petites images, inline_data convient. Pour tout ce qui est volumineux, comme les longues vidéos, les gros PDF ou les fichiers réutilisés d'un appel à l'autre, uploadez une fois avec la Files API et passez une référence à la place :

python
uploaded = client.files.upload(file="contract.pdf")
response = client.models.generate_content(
    model="gemini-3-pro-preview",
    contents=["Summarize the indemnification clauses.", uploaded],
)
print(response.text)

Vous pouvez passer directement des chaînes simples et des objets fichier, le SDK les convertit en parts pour vous. La forme explicite en dict du premier exemple est la même chose, écrite en toutes lettres.

Le contexte long, utilisé à bon escient

La fenêtre de contexte de Gemini est assez grande pour contenir des documents entiers, des codebases ou des transcriptions. Pour de nombreuses tâches, vous pouvez donc mettre le contenu directement dans contents et vous passer de retrieval. Parfois, le « RAG » le plus simple consiste à ne pas faire de RAG du tout, juste à mettre tout le corpus dans le prompt.

Cela a toutefois un coût. Plus de tokens signifie plus de coût et plus de latence, et les contextes très longs peuvent diluer l'attention portée au seul détail qui vous intéresse. Tout coller est un piège quand un extrait ciblé et pertinent suffirait. Utilisez le contexte long quand la tâche l'exige, et n'en faites pas votre réglage par défaut.

La configuration qui modifie le comportement

Passez un config pour contrôler la génération. Deux paramètres sont utiles tout de suite.

Sortie structurée. Inutile de demander du JSON dans le prompt en espérant que ça marche. Vous pouvez contraindre le modèle à un schéma, et Gemini renverra un JSON valide qui le respecte.

python
from google import genai
from pydantic import BaseModel

class Invoice(BaseModel):
    total: float
    due_date: str

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents=["Extract total and due date.", uploaded],
    config={
        "response_mime_type": "application/json",
        "response_schema": Invoice,
    },
)

invoice = response.parsed  # un objet Invoice typé
print(invoice.total, invoice.due_date)

response.parsed vous donne un véritable objet Python au lieu d'une chaîne qu'il faut passer à json.loads en croisant les doigts. C'est ainsi que vous rendez les appels Gemini sûrs à brancher dans du code en aval.

Instructions système. Définissez un comportement persistant avec system_instruction dans le config plutôt que de le répéter dans chaque prompt :

python
config={"system_instruction": "You are a terse financial analyst. Cite figures exactly as written."}

Les paramètres temperature, max_output_tokens et thinking_config se trouvent aussi ici. Les modèles Gemini 3 raisonnent avant de répondre, et vous contrôlez l'ampleur de ce raisonnement avec thinking_level dans thinking_config (par exemple {"thinking_config": {"thinking_level": "low"}}). Utilisez low pour la rapidité sur les extractions simples et high pour les problèmes difficiles. Les anciens modèles 2.5 utilisaient à la place un thinking_budget numérique, attendez-vous donc à voir les deux dans les tutoriels. Pour Gemini 3, Google recommande de laisser temperature à sa valeur par défaut de 1.0.

Gemini API in Python: Getting Started

Watch on YouTube

Le grounding avec Google Search

Peu d'autres API proposent cela : vous pouvez laisser Gemini ancrer ses réponses dans des résultats Google Search en temps réel, avec citations, via une seule entrée tool dans le config.

python
from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="What changed in the latest Gemini API pricing?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    ),
)

print(response.text)

Le modèle décide quand chercher, lance les requêtes et rédige une réponse, avec les sources jointes dans les métadonnées de la réponse. Pour les questions factuelles et sensibles à la date, c'est la solution la plus propre au problème des connaissances obsolètes, et elle est intégrée. Les détails sont dans la documentation sur le grounding.

Vérification des acquis

1. Dans l'appel Gemini multimodal présenté, comment l'image est-elle fournie au modèle en même temps que le prompt texte ?

2. Pourquoi la leçon recommande-t-elle d'utiliser un alias figé et daté comme 'gemini-2.5-flash' plutôt que de toujours sélectionner le modèle le plus récent ?

3. Pour une tâche d'extraction de données de factures à fort volume, quel niveau de Gemini la leçon recommande-t-elle, et pourquoi ?

CHOIX MULTIPLES

4. Sélectionnez TOUTES les affirmations correctes sur le SDK Google GenAI et le client, tels que décrits dans la leçon.

Sélectionnez toutes les réponses correctes.

CHOIX MULTIPLES

5. Sélectionnez TOUTES les affirmations correctes sur la distinction entre la Gemini Developer API et Vertex AI.

Sélectionnez toutes les réponses correctes.

Streaming, chat et erreurs

Quelques points pratiques avant de mettre en production.

Streaming. Pour tout ce qu'un humain attend, streamez les tokens au fur et à mesure au lieu de bloquer jusqu'à la réponse complète :

python
for chunk in client.models.generate_content_stream(
    model="gemini-3-flash-preview",
    contents="Explain native multimodality in two sentences.",
):
    print(chunk.text, end="", flush=True)

Sessions de chat. Pour les conversations multi-tours, client.chats.create(model=...) conserve l'historique pour vous. Vous appelez chat.send_message(...) et il se souvient des tours précédents, vous n'avez donc pas à reconstruire la transcription à la main.

Erreurs et limites. Les clés du free tier ont des rate limits, et vous recevrez des réponses 429 sous charge : prévoyez des retries avec backoff. RESOURCE_EXHAUSTED signifie un quota atteint. INVALID_ARGUMENT signifie que votre requête est mal formée, souvent à cause d'un mauvais type MIME ou d'un payload inline trop volumineux. Quand les données inline deviennent lourdes, passez à la Files API. Cela règle une part étonnante des échecs des débuts. Surveillez aussi les erreurs liées aux identifiants de modèles retirés quand Google déprécie une ancienne génération.

AI Studio : prototyper, puis exporter

N'écrivez pas de Python pour explorer. Ouvrez AI Studio, collez votre prompt, déposez une image, activez la sortie structurée et le grounding, ajustez les paramètres et observez le résultat. Quand le prompt se comporte bien, cliquez sur « Get code » et AI Studio génère l'appel google-genai exact, identifiant de modèle et config compris. Votre boucle devient : expérimenter dans AI Studio, exporter, puis affiner dans votre éditeur.

AI Studio est aussi l'endroit où vous vérifiez la consommation de tokens et comparez des modèles côte à côte avant d'en retenir un pour la production.

Quand passer plutôt à Vertex AI

La clé de la Developer API convient bien aux prototypes et aux petites applications. Passez à Vertex AI quand vous avez besoin d'IAM au niveau de l'organisation, de garanties de résidence des données, de VPC Service Controls, de chiffrement géré par le client ou d'une facturation Google Cloud consolidée. Le même code google-genai se transpose : vous basculez le client en mode Vertex et vous vous authentifiez via Google Cloud plutôt qu'avec une clé API. Voir cloud.google.com/vertex-ai. La décision relève de la gouvernance et de l'échelle. Les modèles sous-jacents sont de la même famille, vous ne gagnez donc pas en capacités en changeant.

Où se situe l'API

L'API est l'un des différents moyens d'accéder à Gemini, et chacun vise un usage distinct. L'application Gemini et les Gems sont des interfaces pour l'utilisateur final. Gemini dans Workspace vit dans Docs et Gmail. Gemini CLI et Code Assist servent les développeurs dans le terminal et l'IDE. L'API est la couche qui se trouve sous vos propres produits. Vous l'appelez quand c'est vous qui construisez l'outil que d'autres utilisent, et tout le contenu de cette leçon porte sur cette couche.

Points clés

  • Installez google-genai, et non l'ancienne google.generativeai. Un seul genai.Client() fonctionne à la fois avec la Developer API d'AI Studio et avec Vertex AI.
  • Partez par défaut sur Gemini 3 Flash et passez à Pro pour le raisonnement difficile. Figez l'identifiant exact du modèle testé et consultez la page des modèles pour les dépréciations.
  • Passez les entrées multimodales sous forme de parts : inline_data pour les petites images, la Files API pour les gros PDF, la vidéo ou tout ce que vous réutilisez.
  • Contraignez la sortie avec `response_schema` et lisez `response.parsed` pour obtenir des objets typés utilisables en toute sécurité en aval.
  • Sur Gemini 3, réglez le raisonnement avec thinking_level. Prototypez dans AI Studio, puis utilisez « Get code » pour exporter l'appel exact.

Questions fréquentes

Quel package Python installer pour appeler l'API Gemini ?

Installez `google-genai` avec `pip install google-genai`. C'est le SDK Google GenAI unifié actuel. Les tutoriels qui importent `google.generativeai` utilisent l'ancienne bibliothèque et ne doivent pas servir de référence pour un nouveau projet.

Quelle est la différence entre Gemini Flash et Gemini Pro, et lequel utiliser ?

Flash est rapide et peu coûteux, et il couvre l'extraction, la classification, le chat et les traitements à fort volume. Pro raisonne mieux sur les problèmes en plusieurs étapes, le code dense et les longues chaînes d'analyse, mais il est plus lent et coûte plus cher par token. Commencez avec Flash et passez à Pro uniquement lorsque Flash montre clairement ses limites. Des variantes Flash-Lite existent pour les cas aux plus gros volumes et au coût le plus bas.

Comment envoyer une image ou un PDF à Gemini dans le même appel que mon prompt ?

Gemini est nativement multimodal : vous passez le texte et les octets ensemble, sous forme de parts, dans la liste `contents`. Utilisez `inline_data` avec un type MIME pour les petites images, et pour les PDF volumineux, les vidéos ou les fichiers réutilisés, chargez-les via la Files API (`client.files.upload`) puis passez la référence obtenue. Pas de gestion du base64, pas d'endpoint vision séparé, pas d'étape d'OCR.

Comment obliger Gemini à renvoyer du JSON valide plutôt que du texte libre ?

Définissez `response_mime_type` sur `application/json` et passez un `response_schema` dans la config, par exemple un modèle Pydantic. Gemini renvoie alors du JSON conforme à ce schéma, et `response.parsed` vous donne un objet Python typé au lieu d'une chaîne à passer à `json.loads`. Demander du JSON dans le prompt seul n'offre aucune garantie de ce type.

Quand passer de la clé API Gemini Developer à Vertex AI ?

Passez-y lorsque vous avez besoin d'IAM au niveau de l'organisation, de garanties de résidence des données, de VPC Service Controls, de chiffrement géré par le client ou d'une facturation Google Cloud consolidée. Le même code `google-genai` reste valable : vous définissez `vertexai=True` avec un projet et une région, et vous vous authentifiez via Google Cloud plutôt qu'avec une clé API. Les modèles sont de la même famille : la migration relève de la gouvernance et du passage à l'échelle, pas des capacités.

Pourquoi l'API Gemini renvoie-t-elle une erreur 429 ou INVALID_ARGUMENT ?

Un `429` avec `RESOURCE_EXHAUSTED` signifie que vous avez atteint la limite de débit ou le quota, ce qui arrive souvent avec les clés du niveau gratuit sous charge : ajoutez un mécanisme de retry avec backoff. `INVALID_ARGUMENT` signifie que la requête est mal formée, le plus souvent à cause d'un type MIME erroné ou d'un payload inline trop volumineux. Basculer ce payload vers la Files API résout une grande partie des échecs des débuts. Vérifiez aussi que l'identifiant du modèle appelé n'a pas été retiré.

À faire, tiré de cette leçon

Ces actions sont compilées dans le plan d'action du rôle.

  • Envoyez PDF, images, audio et vidéo nativement dans une seule requête
  • Prototypez visuellement dans AI Studio, puis récupérez le code avec une clé en variable d'environnement
Voir le plan d'action complet →