Comment utiliser l'API Google Gemini en 2026 (Débutant)

Introduction

L'API Google Gemini, lancée par Google en 2023 et maturisée en 2026, donne accès à des modèles d'IA multimodaux puissants comme Gemini 1.5 Pro et Flash. Contrairement aux APIs fermées comme GPT, Gemini excelle en raisonnement multimodal (texte, images, audio) et en efficacité coût/performance.

Ce tutoriel débutant vous guide pas à pas pour l'intégrer en Node.js avec TypeScript. Vous apprendrez à obtenir une clé API gratuite via Google AI Studio, générer du texte, créer un chat contextuel, analyser des images et streamer des réponses. Chaque exemple est complet et fonctionnel, prêt à copier-coller. Idéal pour prototypes rapides ou apps de production.

Pourquoi Gemini en 2026 ? Tarifs bas (0,00025$/1k tokens), latence faible et intégration native avec Vertex AI pour scalabilité. À la fin, vous maîtriserez 80% des cas d'usage courants.

Prérequis

Node.js 20+ installé
Compte Google gratuit pour AI Studio (clé API en 1 min)
Connaissances basiques en TypeScript/JavaScript
Éditeur comme VS Code
npm ou yarn

1. Initialiser le projet et installer les dépendances

terminal

mkdir gemini-api-tutorial
cd gemini-api-tutorial
npm init -y
npm install @google/generative-ai typescript ts-node dotenv
npm install -D @types/node

Cette commande crée un projet Node.js, installe le SDK officiel @google/generative-ai pour interagir avec Gemini, ainsi que TypeScript, ts-node pour exécuter TS directement et dotenv pour gérer la clé API en sécurité. Évitez d'exposer votre clé dans le code source.

2. Configurer la clé API avec .env

.env

GEMINI_API_KEY=your_api_key_here

Remplacez your_api_key_here par votre clé obtenue sur AI Studio. Ce fichier .env est ignoré par Git (.gitignore automatique avec npm init). Ne commitez jamais de clés API pour éviter les fuites de sécurité.

Configuration TypeScript

Créez un tsconfig.json basique pour une compilation stricte :

``json { "compilerOptions": { "target": "ES2022", "module": "NodeNext", "strict": true } }`

Ajoutez .env à .gitignore : echo ".env" >> .gitignore`.

3. Génération de texte simple

generate-text.ts

import { GoogleGenerativeAI } from '@google/generative-ai';
import dotenv from 'dotenv';

dotenv.config();

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY || '');
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });

async function generateText() {
  const prompt = 'Explique-moi l\'IA en 50 mots.';
  const result = await model.generateContent(prompt);
  const response = await result.response;
  const text = response.text();
  console.log(text);
}

generateText().catch(console.error);

Ce script initialise le client AI avec votre clé, sélectionne le modèle rapide 'gemini-1.5-flash' et génère du contenu à partir d'un prompt. Exécutez avec npx ts-node generate-text.ts. Piège : toujours vérifier si GEMINI_API_KEY existe pour éviter les erreurs 401.

4. Conversation contextuelle (chat)

chat.ts

import { GoogleGenerativeAI } from '@google/generative-ai';
import dotenv from 'dotenv';

dotenv.config();

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY || '');
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });

async function chat() {
  const chat = model.startChat({
    history: [
      {
        role: 'user',
        parts: [{ text: 'Bonjour, qui es-tu ?' }]
      },
      {
        role: 'model',
        parts: [{ text: 'Je suis Gemini, un modèle IA de Google.' }]
      }
    ],
    generationConfig: { maxOutputTokens: 100 }
  });

  const result = await chat.sendMessage('Quelle est la capitale de la France ?');
  const response = await result.response;
  console.log(response.text());
}

chat().catch(console.error);

Ici, on crée un chat avec historique pour maintenir le contexte, limitant les tokens de sortie à 100 pour l'efficacité. Utilisez startChat() pour des sessions persistantes. Attention : l'historique grandit ; tronquez-le pour éviter les quotas.

Passer à la multimodalité

Gemini gère texte + images. Pour tester, préparez une image locale (ex: image.jpg). En 2026, les modèles 1.5+ excellent en vision avec contexte jusqu'à 1M tokens.

5. Analyse d'image (multimodal)

analyze-image.ts

import { GoogleGenerativeAI } from '@google/generative-ai';
import dotenv from 'dotenv';
import fs from 'fs';

dotenv.config();

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY || '');
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });

async function analyzeImage() {
  const imagePart = {
    inlineData: {
      data: Buffer.from(fs.readFileSync('image.jpg')).toString('base64'),
      mimeType: 'image/jpeg'
    }
  };
  const result = await model.generateContent(['Décris cette image en détail.'], { contents: [imagePart] });
  const response = await result.response;
  console.log(response.text());
}

analyzeImage().catch(console.error);

Le code lit une image locale, l'encode en base64 et l'envoie avec un prompt. Placez image.jpg dans le dossier racine. Piège : MIME type exact obligatoire ; gérez les tailles >20MB via URL pour production.

6. Streaming de réponses

stream.ts

import { GoogleGenerativeAI } from '@google/generative-ai';
import dotenv from 'dotenv';

dotenv.config();

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY || '');
const model = genAI.getGenerativeModel({ model: 'gemini-1.5-pro' });

async function streamResponse() {
  const prompt = 'Raconte une histoire courte.';
  const result = await model.generateContent(prompt);
  const stream = model.streamGenerativeContent(prompt);
  for await (const chunk of stream.stream) {
    const response = await chunk.response;
    process.stdout.write(response.text());
  }
}

streamResponse().catch(console.error);

Utilisez streamGenerativeContent() pour des réponses en temps réel, idéal pour les UIs chat. 'gemini-1.5-pro' pour qualité supérieure. Évitez les streams infinis ; ajoutez timeouts et buffers pour les apps web.

7. Script utilitaire complet avec gestion d'erreurs

gemini-utils.ts

import { GoogleGenerativeAI, GenerativeModel } from '@google/generative-ai';
import dotenv from 'dotenv';

dotenv.config();

class GeminiUtils {
  private genAI: GoogleGenerativeAI;
  private model: GenerativeModel;

  constructor() {
    const apiKey = process.env.GEMINI_API_KEY;
    if (!apiKey) throw new Error('GEMINI_API_KEY manquante');
    this.genAI = new GoogleGenerativeAI(apiKey);
    this.model = this.genAI.getGenerativeModel({ model: 'gemini-1.5-flash' });
  }

  async generate(prompt: string): Promise<string> {
    try {
      const result = await this.model.generateContent(prompt);
      return result.response.text() || 'Erreur de génération';
    } catch (error) {
      throw new Error(`Erreur API: ${error}`);
    }
  }
}

const utils = new GeminiUtils();
utils.generate('Bonjour !').then(console.log).catch(console.error);

Une classe réutilisable encapsule le client avec validation de clé et try-catch. Parfait pour apps scalables. Étendez-la pour logging ou retry. Toujours typer les erreurs pour un debugging rapide.

Bonnes pratiques

Sécurisez la clé : Utilisez des secrets managers (Vercel, AWS Secrets) en prod, jamais en client-side.
Limitez les tokens : generationConfig: { maxOutputTokens: 1024, temperature: 0.7 } pour contrôle.
Rate limiting : 60 RPM gratuit ; implémentez queues pour bursts.
Prompt engineering : Soyez spécifique, utilisez rôles (user/system).
Monitoring : Loggez usage via usageMetadata pour optimiser coûts.

Erreurs courantes à éviter

Clé invalide (401) : Vérifiez expiration sur AI Studio ; régénérez si besoin.
Quota dépassé : Gratuit = 15 RPM/1M tokens/jour ; upgradez à payant.
Prompt trop long : Limite 1M tokens entrée ; chunker les docs.
Pas de await : Oubliez await result.response → undefined.
Base64 image corrompue : Vérifiez encoding et MIME.

Pour aller plus loin

Docs officielles : Gemini API Reference
Vertex AI pour prod : scalabilité GCP
Intégrez à Next.js : Tutoriel avancé

Découvrez nos formations IA Learni Group pour maîtriser Fine-tuning et RAG.

Comment utiliser l'API Google Gemini en 2026