Gemini API JavaScript — Integrare l'Intelligenza Artificiale di Google in Node.js e Browser

Hai un'app Node.js che deve generare descrizioni prodotto in tempo reale? Un sito web che vuole un assistente AI lato client senza appesantire il server? La Gemini API di Google ti dà accesso a modelli di linguaggio avanzati, ma integrarla in JavaScript — sia lato server che browser — ha le sue particolarità. Noi, di Meteora Web, ci siamo passati: dalla gestione delle chiavi API all'handling degli stream. In questa guida vediamo come fare.

Come si integra Gemini API in un'app Node.js?

Su Node.js, la libreria ufficiale @google/generative-ai gestisce autenticazione e chiamate. La installi con npm, configuri la chiave API e inizi a dialogare. Il problema? Molti sviluppatori trattano l'API come un black box — noi preferiamo capire ogni request. Ecco il setup base.

Installazione e configurazione della chiave API

npm install @google/generative-ai

La chiave API la prendi da Google AI Studio. Non dimenticare di proteggerla con variabili d'ambiente, mai hardcoded.

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

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

const result = await model.generateContent('Ciao, chi sei?');
console.log(result.response.text());

Attenzione: l'import funziona in ambiente ES Modules. Se usi CommonJS, usa require.

Gestione errori e retry

Le API hanno rate limit. Noi usiamo un semplice retry con backoff:

async function safeGenerate(prompt, retries = 3) {
  try {
    const result = await model.generateContent(prompt);
    return result.response.text();
  } catch (err) {
    if (retries > 0 && err.status === 429) {
      await new Promise(r => setTimeout(r, 2000));
      return safeGenerate(prompt, retries - 1);
    }
    throw err;
  }
}

Come si utilizza Gemini API nel browser senza esporre la chiave segreta?

La chiave API non va mai nel frontend. La soluzione? Un proxy Node.js (o serverless) che fa da intermediario. Oppure, se il tuo caso d'uso è protetto, puoi usare Firebase Auth + Google Cloud Endpoints. Noi preferiamo creare un endpoint semplice con Express.

Proxy server per il browser

// server.js (Node.js)
app.post('/api/gemini', async (req, res) => {
  try {
    const { prompt } = req.body;
    const result = await safeGenerate(prompt);
    res.json({ text: result });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

Dal browser, una fetch normale:

const response = await fetch('/api/gemini', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'Spiega la relatività in una riga' })
});
const data = await response.json();
console.log(data.text);

Mai esporre la chiave. Un server in mezzo è la sicurezza minima.

Come gestire lo streaming delle risposte con Gemini API JavaScript?

Le risposte in streaming migliorano l'UX: il testo appare parola per parola, senza far aspettare il completamento. Gemini supporta generateContentStream. In Node.js:

const stream = await model.generateContentStream(prompt);
for await (const chunk of stream.stream) {
  process.stdout.write(chunk.text());
}

Nel browser, via proxy con SSE (Server-Sent Events) o WebSocket. Noi consigliamo SSE per semplicità. Ecco un esempio lato server:

// proxy con SSE
app.get('/api/gemini/stream', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  const prompt = req.query.prompt;
  const stream = await model.generateContentStream(prompt);
  for await (const chunk of stream.stream) {
    res.write(`data: ${JSON.stringify({ text: chunk.text() })}\n\n`);
  }
  res.end();
});

Lato client, ascolti con EventSource:

const evtSource = new EventSource(`/api/gemini/stream?prompt=${encodeURIComponent('Racconta una storia breve')}`);
evtSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.text); // accumula in un div
};

Quali differenze tra l'integrazione Gemini API in Node.js e nel browser?

La libreria @google/generative-ai funziona sia in Node.js che in browser (con bundler come Webpack o Vite), ma attenzione: nel browser la chiave è esposta se non usi proxy. Inoltre, il supporto nativo per fetch è diverso: su Node 18+ puoi usare fetch senza polyfill. Su browser, devi gestire CORS: se chiami direttamente l'API di Google dal frontend, ti serve un'origin autorizzata. Noi evitiamo sempre chiamate dirette dal client per sicurezza.

Un'altra differenza: la gestione delle dipendenze. Su Node.js installi il pacchetto npm; su browser carichi via CDN o bundle. Ecco un esempio via CDN:

<script type="module">
  import { GoogleGenerativeAI } from 'https://cdn.jsdelivr.net/npm/@google/generative-ai/+esm';
  // ... ma poi devi usare un proxy per evitare di esporre la chiave
</script>

Come ottimizzare il costo delle chiamate Gemini API in JavaScript?

I modelli hanno prezzi per token. Noi consigliamo: usa modelli più piccoli (flash) per compiti semplici, cache le risposte ripetute con Redis o in-memory, e tronca i prompt lunghi. Esempio di caching in Node.js:

const cache = new Map();
async function generateWithCache(prompt) {
  if (cache.has(prompt)) return cache.get(prompt);
  const result = await generateContent(prompt);
  cache.set(prompt, result);
  setTimeout(() => cache.delete(prompt), 3600000); // scade dopo 1h
  return result;
}

Misura sempre i token con await model.countTokens(prompt) prima di chiamare.

Cosa fare adesso

• Prova il setup base. Installa la libreria, genera la prima risposta. Poi aggiungi error handling e retry.
• Crea un endpoint proxy. Per integrazioni browser, separa server e frontend. Mai chiave nel client.
• Implementa streaming se la UX è importante. Sia Node.js che via SSE per il browser.
• Monitora i costi. Abilita token counting e caching per casi d'uso ripetitivi.
• Leggi la documentazione ufficiale di Google Gemini API per modelli e parametri.

Se vuoi approfondire l'ecosistema Gemini per sviluppatori, abbiamo una guida pillar completa che copre l'intera API.