L'API Gemini : vos premiers appels réels

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 faisant quelque chose de spécifique à 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-2.5-flash",
    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 gymnastique base64, pas d'endpoint vision séparé, pas de préprocesseur OCR. Vous passez au modèle des octets et du texte ensemble, et il lit les deux. Décortiquons ce qui est spécifique à Gemini ici, car c'est là que se trouve la valeur.

Le SDK et le client

Le package s'appelle google-genai, le SDK unifié Google GenAI. 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 legacy. 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 est sur ai.google.dev.

Un SDK, deux backends. Le même client s'adresse soit à l'API Gemini Developer (la clé AI Studio, rapide à démarrer), soit à Vertex AI (Google Cloud, avec IAM, contrôles VPC et facturation entreprise). Vous basculez en définissant vertexai=True avec un projet et une localisation, pas en réécrivant votre code. Prototypez sur l'API Developer, passez à Vertex quand vous avez besoin de gouvernance. Nous traitons ce basculement plus loin dans ce parcours.

Choisir le modèle : flash vs pro

La chaîne model est une vraie décision, pas une formalité. Gemini se décline en gammes :

• Flash est le cheval de trait : rapide, peu coûteux, excellent pour l'extraction, la classification, le chat et les traitements à fort volume. La tâche de facture ci-dessus est un travail pour Flash.
• Pro est le raisonneur : problèmes multi-étapes plus difficiles, code dense, longues chaînes analytiques. 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 →.
• Des variantes Flash-Lite existent pour les cas à très fort volume et coût minimal.

Utilisez un alias daté et figé comme gemini-2.5-flash plutôt que de courir après le plus récent. Les identifiants de modèles évoluent, vérifiez donc la liste à jour dans AI Studio ou sur la page des modèles avant de mettre en production. Le principe reste valable même quand les numéros de version montent : commencez par Flash, n'escaladez vers Pro que quand Flash peine visiblement.

Pourquoi cela compte davantage avec Gemini

Gemini est nativement multimodal : texte, images, audio, vidéo et PDF passent par le même modèle plutôt que par un module de vision greffé. Le compromis coût/latence entre Flash et Pro s'applique donc aussi au traitement d'images et de documents, pas seulement au texte. 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 morceau d'entrée : une part text, une part inline_data (octets bruts plus un type MIME), ou une référence vers un fichier uploadé. Le modèle les voit dans l'ordre, donc le placement du prompt compte. Mettre l'instruction avant l'image, comme ci-dessus, fonctionne généralement bien pour les tâches du type « fais X à cette chose ».

Pour de petites images, inline_data convient. Pour tout ce qui est volumineux (longue vidéo, gros PDF, fichiers réutilisés sur plusieurs appels), uploadez une fois avec la Files API et passez un handle à la place :

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

Notez que vous pouvez passer directement des chaînes de caractères et des objets fichier ; le SDK les emballe en parts pour vous. La forme explicite en dictionnaire du premier exemple, c'est exactement la même chose écrite en détail.

Le long contexte, utilisé à bon escient

La fenêtre de contexte longue de Gemini est suffisamment large pour que vous puissiez déposer des documents entiers, des bases de code ou des transcriptions directement dans contents et faire l'économie du retrieval pour beaucoup de tâches. C'est un vrai changement dans la conception : 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, c'est pas de RAG du tout, juste le corpus entier dans le prompt.

Mais ce n'est pas gratuit. Plus de tokens, c'est plus de coût et plus de latence, et des contextes très longs peuvent diluer l'attention sur le seul détail qui vous intéresse. Le réflexe de tout coller est un piège quand une tranche courte et pertinente ferait l'affaire. Traitez le long contexte comme un outil que vous choisissez, pas comme un réglage par défaut sur lequel vous vous reposez.

La configuration qui change le comportement

Passez un config pour piloter la génération. Deux réglages sont rentables immédiatement.

Structured output. Au lieu d'implorer le modèle de produire du JSON dans le prompt en croisant les doigts, vous pouvez le contraindre à 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 →. Gemini renverra un JSON valide conforme.

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-2.5-flash",
    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 rend un véritable objet Python, pas une chaîne qu'il faut passer à json.loads en priant. C'est ainsi que vous rendez les appels Gemini sûrs à brancher dans du code en aval.

System instructions. Définissez un comportement persistant avec system_instruction dans la config plutôt que de l'enterrer dans chaque prompt :

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

Les réglages temperature, max_output_tokens et thinking_config se trouvent aussi ici. Ce dernier est spécifique à Gemini : sur les modèles capables de raisonnement, vous pouvez ajuster le thinking budget, la quantité de raisonnement interne que le modèle dépense avant de répondre. Baissez-le pour gagner en vitesse sur les tâches faciles, augmentez-le pour les tâches difficiles.

Le grounding avec Google Search

Voici une capacité que vous ne trouverez pas sur la plupart des API : vous pouvez laisser Gemini ancrer ses réponses dans des résultats Google Search en direct, avec citations, via un seul flag de config.

from google import genai
from google.genai import types

client = genai.Client()
response = client.models.generate_content(
    model="gemini-2.5-flash",
    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, exécute les requêtes et synthétise une réponse avec les sources attachées dans les métadonnées de la réponse. C'est la façon la plus propre de lutter contre les connaissances périmées sur des questions factuelles et sensibles au temps, et c'est intégré plutôt qu'à assembler soi-même. Les détails sont dans la documentation grounding.

Streaming, chat et erreurs

Trois points pratiques avant la mise en production.

Streaming. Pour tout ce qu'un humain attend, diffusez 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-2.5-flash",
    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 ne reconstruisez pas la transcription complète à la main chaque fois.

Erreurs et limites. Les clés du tier gratuit ont des rate limits, et vous rencontrerez des réponses 429 en charge. Prévoyez du retry avec backoff. Surveillez RESOURCE_EXHAUSTED (quota) par opposition à INVALID_ARGUMENT (votre requête est mal formée, souvent un mauvais type MIME ou un payload inline trop volumineux). Quand les données inline deviennent grosses, passez à la Files API ; cela règle une part surprenante des échecs de début.

AI Studio : prototyper, puis exporter

N'écrivez pas de Python pour explorer. Ouvrez AI Studio, collez votre prompt, déposez une image, activez structured output et grounding, réglez la temperaturetemperatureUn reglage qui controle le caractere aleatoire ou previsible des reponses d'un modele d'IA : bas pour la coherence, haut pour la creativite.Voir la définition complète → 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 inclus. Votre boucle devient : expérimenter dans AI Studio, exporter, puis affiner dans votre éditeur.

C'est aussi là que vous vérifiez la consommation de tokens et comparez les modèles côte à côte avant d'en engager un en production.

Quand opter plutôt pour Vertex AI

La clé de l'API Developer est parfaite pour les prototypes et les petites applications. Passez à Vertex AI dès que vous avez besoin de l'un de ces éléments : IAM et contrôle d'accès au niveau de l'organisation, 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 →, VPC Service Controls, chiffrement géré par le client, ou facturation Google Cloud consolidée. Le même code google-genai se transpose ; vous basculez le client en mode Vertex et vous authentifiez via Google Cloud au lieu d'une clé d'API. Voir cloud.google.com/vertex-ai. La décision porte sur la gouvernance et l'échelle, pas sur les capacités, puisque les modèles sous-jacents sont de la même famille.

Une remarque sur la place de l'API

L'API est l'une des plusieurs façons d'atteindre Gemini, et chacune vise des usages différents. L'application Gemini et les Gems sont des surfaces destinées à l'utilisateur final. Gemini dans Workspace vit à l'intérieur de Docs et Gmail. Gemini CLI et Code Assist servent les développeurs dans le terminal et l'IDE. L'API est la couche sous vos propres produits : c'est ce que vous appelez quand c'est *vous* qui construisez la chose que d'autres utilisent. Tout dans cette leçon relève de cette couche de builder.

Points clés

• Installez `google-genai`, pas la legacy `google.generativeai`. Un SDK, un genai.Client(), et le même code tourne à la fois contre l'API Developer d'AI Studio et Vertex AI.
• Prenez Flash par défaut, escaladez vers Pro. Flash gère l'extraction, le chat et les traitements à fort volume à faible coût ; réservez Pro au raisonnement réellement difficile, et figez un identifiant de modèle daté plutôt que de courir après le plus récent.
• Passez les entrées multimodales sous forme de parts. Utilisez inline_data pour les petites images et la Files API pour les gros PDF, la vidéo ou tout ce que vous réutilisez, et rappelez-vous que Gemini les lit nativement en un seul appel.
• Contraignez la sortie avec `response_schema` et lisez `response.parsed`. Cela transforme la sortie du modèle en objets typés que vous pouvez brancher sans risque dans du code en aval.
• Prototypez dans AI Studio, puis « Get code ». Réglez les prompts, le grounding et la config visuellement sur aistudio.google.com, exportez l'appel exact, et seulement ensuite passez dans votre éditeur.