Gemini 2.5 Pro Beginner Guide: Search, Create, and Analyze

Your First Hour with Gemini 2.5 Pro

If you've got 60 minutes and want to go from zero to a working Gemini 2.5 Pro integration, this guide is for you. I've walked about 300 developers through this process at workshops and meetups over the past two months, and the pattern that works best is: get something running first, then understand why it works.

I'm not going to bury you in theory. We'll get an API key, make our first call, build something useful, and handle the gotchas that trip up most newcomers. By the end, you'll have a working project and enough understanding to start building your own ideas.

Step 1: Getting Your API Key (5 minutes)

Head to Google AI Studio at aistudio.google.com. If you've got a Google account, you're already halfway there. Click "Get API Key" in the left sidebar, then "Create API Key." You can either create a new Google Cloud project or use an existing one.

A few things that trip people up at this stage:

The free tier gives you 60 requests per minute for Gemini 2.5 Pro, which is plenty for development. You won't need to set up billing unless you're going to production or hitting rate limits during testing. That said, if you're building something serious, link a billing account early — the free tier has a daily request cap that isn't well documented, and hitting it mid-debug is frustrating.

Store your API key in an environment variable, not in your code. This isn't optional advice — it's the difference between a secure project and a leaked credential in your GitHub history. Create a .env file:

GEMINI_API_KEY=your_key_here

And add .env to your .gitignore. I've seen three separate developers push API keys to public repos in the last month alone. Google rotates compromised keys automatically, but the hassle of updating your configuration isn't worth the 10 seconds you save by hardcoding.

Step 2: Your First API Call (10 minutes)

Let's keep it simple. We'll use Node.js with the official SDK, though Python works just as well. Install the package:

npm install @google/genai

Here's your first script — save it as index.mjs:

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-pro",
  contents: "Explain the difference between REST and GraphQL in two paragraphs.",
});

console.log(response.text);

Run it with node --env-file=.env index.mjs and you should see a coherent explanation within about 2-4 seconds. If you get an authentication error, double-check your API key and make sure the .env file is loading correctly — --env-file requires Node.js 20.6+.

If you're using Python instead, the equivalent is:

from google import genai

client = genai.Client(api_key="your_key_here")
response = client.models.generate_content(
    model="gemini-2.5-pro",
    contents="Explain the difference between REST and GraphQL in two paragraphs."
)
print(response.text)

One thing to notice: the response includes not just the text but metadata about token usage. Gemini 2.5 Pro charges $1.25 per million input tokens and $5 per million output tokens. A typical query like this uses about 150 input tokens and 200 output tokens — roughly $0.001 per call. You'd need to make a thousand calls to spend a dollar.

Step 3: Building a Document Analyzer (25 minutes)

Let's build something actually useful. We'll create a tool that takes a PDF document, extracts its content, and generates a structured summary with key points. This uses Gemini 2.5 Pro's multimodal capabilities — specifically, its ability to process images (PDF pages rendered as images).

First, install the PDF rendering library:

npm install pdf2pic

Here's the complete analyzer:

import { GoogleGenAI } from "@google/genai";
import { fromPath } from "pdf2pic";
import fs from "fs";

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

async function analyzeDocument(pdfPath) {
  // Convert PDF pages to images
  const converter = fromPath(pdfPath, {
    density: 150,
    saveFilename: "page",
    format: "png",
  });

  const pageCount = 5; // adjust based on your document
  const images = [];

  for (let i = 1; i <= pageCount; i++) {
    const result = await converter(i);
    const imageData = fs.readFileSync(result.path, { encoding: "base64" });
    images.push({
      inlineData: {
        mimeType: "image/png",
        data: imageData,
      },
    });
  }

  const response = await ai.models.generateContent({
    model: "gemini-2.5-pro",
    contents: [
      ...images,
      {
        text: "Analyze this document. Return a JSON object with: title, summary (2-3 sentences), keyPoints (array of strings), and documentType (one of: report, proposal, manual, article, other).",
      },
    ],
    config: {
      responseMimeType: "application/json",
    },
  });

  const parsed = JSON.parse(response.text);
  console.log(JSON.stringify(parsed, null, 2));
  return parsed;
}

analyzeDocument("./sample.pdf");

A few things worth noting about this code. We're using responseMimeType: "application/json" to force structured output — this is a Gemini-specific feature that guarantees valid JSON. Without it, you'd get JSON wrapped in markdown code blocks about 80% of the time, with the other 20% being free-form text that happens to mention JSON-like structures.

The pdf2pic library converts PDF pages to PNG images. We're rendering at 150 DPI, which provides a good balance between image quality and API token cost. Higher DPI means more tokens consumed per page. For text-heavy documents, 150 DPI is sufficient. For documents with fine print or complex diagrams, bump it to 200.

The base64 encoding increases the payload size, but Gemini handles the internal image processing efficiently. A typical A4 page at 150 DPI produces about 1-2K tokens of processed image data.

Step 4: Adding Search Grounding (10 minutes)

One of Gemini 2.5 Pro's standout features is Google Search grounding — the ability to augment responses with real-time web search results. This is incredibly useful for keeping information current.

Here's how to enable it:

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-pro",
  contents: "What are the latest features in React 19?",
  config: {
    tools: [{ googleSearch: {} }],
  },
});

console.log(response.text);

// Check grounding metadata
if (response.candidates?.[0]?.groundingMetadata) {
  const sources = response.candidates[0].groundingMetadata
    .searchEntryPoint?.renderedContent;
  console.log("\nSources:", sources);
}

The grounding metadata tells you which search results informed the response. This is critical for trust — you can verify the sources rather than taking the model's word at face value. I recommend always displaying grounding sources to end users when using search-augmented responses.

One gotcha: search grounding adds latency (typically 1-3 extra seconds) because the model needs to perform the search, process results, and synthesize a response. For real-time applications, consider caching search-grounded responses for 15-30 minutes.

Another gotcha: search grounding isn't available in all regions. If you're building for international users, test with VPN endpoints in your target countries. We found it unavailable in about 8 countries during our testing in February 2026.

Step 5: Error Handling and Rate Limits (10 minutes)

The API will fail. Plan for it. Here's a robust error handling pattern:

async function generateWithRetry(prompt, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await ai.models.generateContent({
        model: "gemini-2.5-pro",
        contents: prompt,
      });
      return response.text;
    } catch (error) {
      if (error.status === 429) {
        // Rate limited — exponential backoff
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Rate limited. Waiting ${delay}ms before retry ${attempt}...`);
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      if (error.status === 500 || error.status === 503) {
        // Server error — retry with linear backoff
        const delay = attempt * 2000;
        console.log(`Server error. Retrying in ${delay}ms...`);
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      // Non-retryable error
      throw error;
    }
  }
  throw new Error(`Failed after ${maxRetries} retries`);
}

The 429 (rate limit) and 500/503 (server errors) are the most common transient failures. The SDK doesn't include built-in retry logic, so you need to handle this yourself. Exponential backoff for rate limits, linear backoff for server errors — that pattern works well across all the Gemini endpoints I've tested.

What to Build Next

You've got the basics. Here are three project ideas that build on what we covered:

Meeting notes summarizer. Record a meeting as audio, transcribe it with Gemini's audio understanding, then generate structured notes with action items. Use the JSON output mode to get machine-parseable action items.

Screenshot-to-code converter. Feed UI screenshots to Gemini 2.5 Pro and ask for React/Tailwind implementations. It won't be pixel-perfect, but it gets you 70-80% of the way there, which is a great starting point for refinement.

Content quality analyzer. Build a tool that analyzes blog posts or marketing copy for readability, SEO structure, and tone consistency. Use search grounding to compare against top-ranking content for the same topic.

Each of these projects exercises different parts of the API — multimodal input, structured output, search grounding, or combinations of all three. Start with whichever excites you most.

The Gemini 2.5 Pro API is stable enough for production use as of March 2026, and the pricing is competitive. Don't overthink the setup — just start building. You'll learn more from one working prototype than from ten documentation pages.