Learning the Gemini API: text, images, and streaming

Gemini is Google’s family of AI models — I use it on several projects (including ColdCanvas), mainly for its generous free tier for experiments and strong multimodal (text + image) abilities. This tutorial uses the current official SDK, @google/genai.

1. Setup

1. Open Google AI Studio → Get API key (free, a Google account is enough).
2. Store it as an environment variable:

export GEMINI_API_KEY="AIza..."

3. Install the official SDK (the new one — not the older @google/generative-ai):

npm install @google/genai

2. Your first call

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Explain the difference between SEO and SEM in 3 sentences.",
});

console.log(response.text);

response.text is a shortcut for the combined text — for simple cases, it’s all you need.

3. System instructions & configuration

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: "Write 5 Instagram caption ideas for a coffee shop.",
  config: {
    systemInstruction: "You are an experienced copywriter for small businesses. Casual tone, no emoji overload.",
    temperature: 0.9,          // higher = more varied
    maxOutputTokens: 1024,
  },
});

4. Multimodal: send images

Gemini’s signature strength — image analysis in the same single call:

import { readFileSync } from "node:fs";

const imageBase64 = readFileSync("product.jpg").toString("base64");

const response = await ai.models.generateContent({
  model: "gemini-2.5-flash",
  contents: [
    { inlineData: { mimeType: "image/jpeg", data: imageBase64 } },
    { text: "Write a marketplace product description from this photo, include 5 search keywords." },
  ],
});

A real e-commerce use case: auto-generating product descriptions from catalog photos.

5. Streaming

const stream = await ai.models.generateContentStream({
  model: "gemini-2.5-flash",
  contents: "Write a short article about Gayo coffee.",
});

for await (const chunk of stream) {
  process.stdout.write(chunk.text ?? "");
}

6. Choosing a model

• gemini-2.5-flash — start here: fast, cheap, multimodal.
• gemini-2.5-pro — deeper reasoning for complex tasks.
• The model family moves fast — always check the current model list in AI Studio before going to production.

Tips from experience

• Gemini’s free tier is the cheapest place to learn LLM APIs — but mind the data policy: on the free tier, inputs may be used for training. For client data, always use the paid tier.
• On scraping + AI projects (like ColdCanvas), the best pattern: a cheap model (flash) for bulk classification, the expensive model only for the final human-read step.
• The concepts from the Claude API tutorial apply identically here: system instruction = business rules, streaming = mandatory for UIs, and never put API keys in code.