L'API Gemini : vos premiers vrais appels
Voici un appel Gemini multimodalmultimodalIA qui traite plusieurs types de contenu à la fois: texte, image, audio, vidéo et données, au lieu d'un seul format.Voir la définition complète → complet en Python : une image, une question, une réponse, chaque élément jouant un rôle propre à Gemini.
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.
pip install google-genai
export GEMINI_API_KEY="your-key-from-aistudio"Récupérez la clé sur aistudio.google.com via « Get APIAPIApplication Programming Interface : une interface standardisée qui permet aux applications de communiquer et d'échanger des données sans connaître leur fonctionnement interne respectif.Voir la définition complète → 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 tokentokenUn token est l'unité de base de texte que traitent les modèles de langage : le plus souvent un fragment de mot, un mot entier ou un signe de ponctuation, plutôt qu'un simple caractère.Voir la définition complète →.
- 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 :
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 « RAGRAGMéthode qui permet à un modèle d'IA de répondre à partir de vos propres documents, en récupérant les passages pertinents avant de générer une réponse.Voir la définition complète → » 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émamaUtiliser un logiciel pour automatiser les tâches et campagnes marketing répétitives, afin de personnaliser à grande échelle sur des canaux comme l'email, le web et le social.Voir la définition complète →, et Gemini renverra un JSON valide qui le respecte.
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 :
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
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.
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 ?
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.
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 :
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éesrésidence des donnéesL'exigence de stocker et traiter les données physiquement dans un pays ou une région précise, souvent pour des raisons légales ou contractuelles.Voir la définition complète →, 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'anciennegoogle.generativeai. Un seulgenai.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_datapour 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