How to Use the Google Gemini API

Ten lines. Install the SDK, set your key, make a request.

# pip install -U google-genai
from google import genai
import os

# Set GEMINI_API_KEY env var or pass directly
client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Explain the CAP theorem in 3 sentences."
)

print(response.text)

Set your API key as an environment variable before running:

# Linux/macOS
export GEMINI_API_KEY="AIza..."

# Windows PowerShell
$env:GEMINI_API_KEY = "AIza..."

# Windows CMD
set GEMINI_API_KEY=AIza...

Get your key from Google AI Studio. No credit card required for free tier. Key starts with AIza -- copy it immediately, the UI won't show it again without regenerating. One key per project, multiple projects allowed.

The unified google-genai package replaced the deprecated google-generativeai. It works with both AI Studio and Vertex AI. The SDK supports Python, Node.js, and Go. REST is also available for any language.

pip install -U google-genai

Verification: Run python -c "from google import genai; print(genai.__version__)". If you see a version number (0.9.x or higher as of March 2026), the install succeeded.

Text Request

from google import genai

client = genai.Client()

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What are the three main types of machine learning?"
)

print(response.text)

Verification: You should see a text response listing supervised, unsupervised, and reinforcement learning. If you get a response, the API key, SDK, and network connection all work.

Multimodal Request (Image)

from google import genai
from google.genai import types

client = genai.Client()
image = client.files.upload(file="screenshot.png")

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=[
        types.Part.from_uri(
            file_uri=image.uri,
            mime_type=image.mime_type
        ),
        "Describe what you see in this image and identify any UI components."
    ]
)

Supports image/png, image/jpeg, image/webp, audio/mp3, audio/wav, video/mp4, and application/pdf.

Structured Output (JSON)

from pydantic import BaseModel

class MovieReview(BaseModel):
    title: str
    rating: float
    sentiment: str
    key_themes: list[str]

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Review the movie Inception",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=MovieReview
    )
)

Always pair response_mime_type with response_schema. Without the schema, the model guesses at structure. Structured output docs.

Search Grounding

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="What were the major AI announcements this week?",
    config=types.GenerateContentConfig(
        tools=[types.Tool(google_search=types.GoogleSearch())]
    )
)

# Access source citations
if response.candidates[0].grounding_metadata:
    for chunk in response.candidates[0].grounding_metadata.grounding_chunks:
        print(f"Source: {chunk.web.title} -- {chunk.web.uri}")

Grounding connects the model to live web data. Free tier: 5,000 grounded prompts/month. Paid: $14 per 1,000 queries. This is where the API pulls ahead for RAG workflows -- built-in search skips the vector database for many retrieval tasks. For production agent workflows, see our guide on Gemini agents and agentic capabilities.

Pick your model based on cost tolerance and reasoning requirements. All models share 1M context window and 64K output token ceiling.

Decision Framework

• Prototyping and testing? Use Gemini 2.5 Flash on free tier. No cost, 10 RPM.
• Production API with cost sensitivity? Gemini 2.5 Flash-Lite at $0.10/1M input. Handles classification, extraction, and summarization.
• Production API needing reasoning? Gemini 2.5 Pro (stable) or 3.1 Pro (preview, higher capability but subject to breaking changes).
• Batch processing at scale? Any model with the Batch API. 50% savings, 24-hour SLA.

Same models, same SDK, different infrastructure layer.

Migration is straightforward -- change client initialization and auth method. Prompts and code structure stay the same. Migration guide. For more context on AI platform choices and governance requirements, the platform decision often depends on your organization's compliance posture more than technical capability.

Limits are per-project, not per-key. Three dimensions tracked simultaneously -- exceeding any one triggers a 429 error.

Free Tier (No Credit Card)

Retry Pattern

import time
from google import genai
from google.api_core import exceptions

client = genai.Client()

def call_with_retry(prompt, model="gemini-2.5-flash", max_retries=3):
    for attempt in range(max_retries):
        try:
            response = client.models.generate_content(
                model=model, contents=prompt
            )
            return response.text
        except exceptions.ResourceExhausted:
            wait = 2 ** attempt
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
    raise Exception("Max retries exceeded")

View your current limits in AI Studio's quota dashboard.

Build a function-calling agent. The API's tool use system lets the model call your functions, inspect results, and chain actions. Combined with grounding and structured output, you have the pieces for a production agentic AI workflow.

New in 3.1: Thought Signatures preserve reasoning context across multi-turn conversations, improving coherence in function-calling and agentic workflows. The media_resolution parameter lets you control how multimodal inputs are tokenized. Gemini 3.1 Flash Live is a new low-latency audio-to-audio model for real-time conversational applications.

Google, Gemini, Google AI Studio, and Vertex AI are trademarks of Google LLC. This article is not affiliated with, sponsored by, or endorsed by Google LLC.