Gemini API Python Tutorial: 2026 Complete Guide to Calling Google AI Models from Scratch

Get Gemini API Running in 5 Minutes

You've already heard that Gemini API is powerful and affordable.

But you open Google's official documentation and find it long and scattered, with no clear starting point.

This tutorial saves you the time of sifting through docs. I'll walk you through Gemini API Python integration from scratch in the simplest steps -- from SDK installation to multimodal applications, with copy-paste-ready code at every step.

Need a Gemini API enterprise plan? Get better pricing through CloudInsight, no overseas payment hassles.

TL;DR

Install the google-generativeai package -> Set API Key -> Create a model instance with GenerativeModel -> Call generate_content() and you're done. This tutorial covers text generation, image understanding, Streaming, and Function Calling, with complete runnable code.

---

Python Environment Preparation & Gemini SDK Installation

Answer-First: All you need is Python 3.9+, pip, and one line pip install google-generativeai to get started.

Environment Requirements

Item	Minimum	Recommended
Python	3.9	3.11+
pip	21.0	Latest
google-generativeai	0.8.0	0.8.x latest
OS	Windows / macOS / Linux	Any

Installation Steps

We recommend creating a virtual environment first to avoid package conflicts:

# Create virtual environment
python -m venv gemini-env

# Activate virtual environment (macOS / Linux)
source gemini-env/bin/activate

# Activate virtual environment (Windows)
gemini-env\Scripts\activate

# Install Gemini SDK
pip install google-generativeai

After installation, verify:

python -c "import google.generativeai as genai; print(genai.__version__)"

If you see a version number, the installation was successful.

Common Installation Issues

• pip version too old: Run pip install --upgrade pip first
• SSL errors: Corporate networks may need proxy configuration
• M1/M2 Mac compatibility: The SDK fully supports Apple Silicon

---

Getting Your Gemini API Key & Setting Up Authentication

Answer-First: Get an API Key in just two clicks at Google AI Studio. Storing it in an environment variable is the safest approach.

Get Your API Key

1. Go to Google AI Studio
2. Log in with your Google account
3. Click "Get API Key" -> "Create API Key"
4. Copy the generated Key

No credit card required to get a free API Key. For complete application steps, see Gemini API Official Documentation & Feature Guide.

Set Up API Key (The Safe Way)

Never hardcode your API Key in source code.

The correct approach is using environment variables:

# macOS / Linux
export GEMINI_API_KEY="your-api-key-here"

# Windows PowerShell
$env:GEMINI_API_KEY="your-api-key-here"

Then read it in Python:

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

If you manage environment variables with .env files, use python-dotenv:

from dotenv import load_dotenv
load_dotenv()

genai.configure(api_key=os.getenv("GEMINI_API_KEY"))

---

Text Generation API Call Implementation with Code Examples

Answer-First: Create a model instance with GenerativeModel, call generate_content() with your Prompt, and get AI-generated text back.

Basic Text Generation

import os
import google.generativeai as genai

genai.configure(api_key=os.environ["GEMINI_API_KEY"])

# Create model instance
model = genai.GenerativeModel("gemini-2.0-flash")

# Call API
response = model.generate_content("Describe Taiwan's night market culture in 3 key points")

# Print result
print(response.text)

That's the simplest usage. 6 lines of code to get Gemini API running.

Adjusting Generation Parameters

You can control generation results via GenerationConfig:

config = genai.GenerationConfig(
    temperature=0.7,       # Creativity level (0-2, higher = more creative)
    top_p=0.9,             # Sampling range
    top_k=40,              # Candidate token count
    max_output_tokens=1024 # Maximum output length
)

response = model.generate_content(
    "Write a short poem about a rainy day in Taipei",
    generation_config=config
)

Parameter recommendations:

Scenario	temperature	top_p	Description
Translation, summarization	0.1-0.3	0.8	Accuracy needed
General Q&A	0.5-0.7	0.9	Balance creativity and accuracy
Creative writing	1.0-1.5	0.95	Diversity needed

Multi-Turn Conversation

chat = model.start_chat(history=[])

response = chat.send_message("Hi! I want to learn Python")
print(response.text)

response = chat.send_message("Can you recommend some beginner books?")
print(response.text)

start_chat() automatically maintains conversation history -- you don't need to manage context manually.

Purchase Gemini API through CloudInsight for exclusive enterprise discounts and uniform invoices. Learn about enterprise plans

---

Multimodal Applications: Image Understanding & Video Analysis

Answer-First: Gemini API natively supports multimodal input -- you can send text + images (or video) simultaneously, letting AI understand visual content and generate text responses.

Image Understanding

import PIL.Image

model = genai.GenerativeModel("gemini-2.0-flash")

# Load local image
img = PIL.Image.open("receipt.jpg")

# Send image + text prompt
response = model.generate_content([
    "Please identify the item names and amounts on this receipt, output in table format",
    img
])

print(response.text)

Supported image formats: JPEG, PNG, GIF, WebP. Maximum 20MB per image.

Multi-Image Comparison

img1 = PIL.Image.open("product_a.jpg")
img2 = PIL.Image.open("product_b.jpg")

response = model.generate_content([
    "Compare the visual differences between these two products",
    img1,
    img2
])

Video Analysis

Gemini API supports direct video file uploads:

video_file = genai.upload_file("demo.mp4")

# Wait for file processing to complete
import time
while video_file.state.name == "PROCESSING":
    time.sleep(2)
    video_file = genai.get_file(video_file.name)

response = model.generate_content([
    "Please generate 5 key takeaways from this video",
    video_file
])

Video analysis is currently a unique Gemini API advantage -- neither OpenAI nor Claude supports direct video uploads.

But note: video analysis consumes a lot of tokens. A 1-minute video uses approximately 4,000-8,000 tokens. Long videos can get expensive.

If you also want to learn OpenAI's Python integration approach, see OpenAI API Python SDK Integration Complete Tutorial. The two APIs have different design philosophies, and learning both helps you choose the best fit for your project.

---

Advanced Techniques: Streaming, Function Calling & Error Handling

Answer-First: Streaming enables real-time response display, Function Calling lets AI call custom functions, and error handling ensures stable production operation. These three advanced techniques are essential for going live.

Streaming Response

Don't want to wait for AI to finish before seeing results? Use Streaming:

response = model.generate_content(
    "Give a detailed introduction to 5 must-visit tourist spots in Taiwan",
    stream=True
)

for chunk in response:
    print(chunk.text, end="", flush=True)

Streaming is especially useful for chatbot scenarios. Users don't have to stare at a blank screen waiting for the AI to finish.

Function Calling

Let AI call functions you define:

def get_weather(city: str) -> dict:
    """Get weather information for a specified city"""
    # Would actually call a weather API
    return {"city": city, "temp": 28, "condition": "Sunny"}

model = genai.GenerativeModel(
    "gemini-2.0-flash",
    tools=[get_weather]
)

chat = model.start_chat()
response = chat.send_message("What's the weather like in Taipei today?")

Gemini automatically determines when to call get_weather and passes the correct city parameter.

Error Handling

Error handling is a must for production environments:

import google.api_core.exceptions as exceptions

try:
    response = model.generate_content("Your Prompt")
    print(response.text)
except exceptions.ResourceExhausted:
    print("Rate limit exceeded, please try again later")
except exceptions.InvalidArgument as e:
    print(f"Invalid request parameters: {e}")
except exceptions.PermissionDenied:
    print("Invalid API Key or insufficient permissions")
except Exception as e:
    print(f"Unknown error: {e}")

Common error codes:

Error Code	Cause	Solution
429	Rate limit exceeded	Add retry logic with increasing intervals
400	Invalid request format	Check Prompt and parameters
403	Invalid API Key	Confirm Key is correct and active
500	Server-side error	Retry later

---

Next Steps: From Practice to Production

You've now learned the complete Gemini API Python integration process.

But there are several things to keep in mind between "it runs" and "it's live":

• API Key security: Never commit to Git; use environment variables or Secret Manager. For more security tips, see API Key Management & Security Best Practices
• Cost monitoring: Set daily usage limits to avoid unexpected overcharges. For cost differences across APIs, see AI API Pricing Comparison Complete Guide
• Model selection: Use Flash for development testing (cheap), choose Pro or Ultra for production based on quality needs
• Rate limits: Implement exponential backoff retry mechanisms

For a comprehensive look at Gemini API features and pricing, see Gemini API Complete Development Guide.

If you have broader interest in Python AI development, Python AI API Integration Beginner's Tutorial covers common concepts and comparisons across providers. For a deeper look at pricing differences, AI API Pricing Comparison Complete Guide is very helpful.

Need an enterprise-grade Gemini API plan? CloudInsight offers bulk token purchase discounts, uniform invoices, and Chinese technical support. Get an enterprise quote now, or join LINE Official Account for instant technical support.

FAQ

Q1: What's the difference between google-generativeai and vertexai SDKs? Which should I use?

Depends on which endpoint you're targeting. Gemini API now has two main Python SDKs: (1) google-generativeai (recommended for beginners) — calls Google AI Studio's API endpoint (generativelanguage.googleapis.com), needs only API key auth, best for personal / prototype development. Install: pip install google-generativeai; example: genai.GenerativeModel('gemini-2.0-flash').generate_content(...). (2) google-cloud-aiplatform (vertexai) — calls Vertex AI's endpoint, requires GCP account and Application Default Credentials, suits enterprise production. Install: pip install google-cloud-aiplatform; example: vertexai.init(project='my-project', location='us-central1'); model = GenerativeModel('gemini-2.0-flash'). Selection principles: (A) personal / learning / prototyping → google-generativeai; (B) company commercial product, need audit logs, data protection → vertexai; (C) already on GCP, want unified IAM management → vertexai. Migration notes: both APIs are similar in design but not identical; code can't be directly swapped but basic call patterns are close — one day to refactor. New SDK: Google launched unified google-genai SDK in 2025 (replacing google-generativeai), supporting both endpoints; for new projects, use this directly.

Q2: How to implement streaming response? How to send to frontend with Flask / FastAPI?

Gemini SDK supports streaming; combining with SSE (Server-Sent Events) to frontend is most common. Python implementation: response = model.generate_content(prompt, stream=True) → for chunk in response: print(chunk.text). FastAPI + SSE complete example: (1) Backend: from fastapi.responses import StreamingResponse; async def generate(): for chunk in response: yield f"data: {chunk.text}\n\n"; return StreamingResponse(generate(), media_type="text/event-stream"); (2) Frontend: const eventSource = new EventSource('/api/chat'); eventSource.onmessage = (e) => { document.getElementById('output').innerText += e.data; }. Flask version: similar but uses yield + Response(stream_with_context(...), mimetype='text/event-stream'). Considerations: (1) CORS headers — SSE may be blocked by browsers; (2) Timeout — some reverse proxies (nginx) default 60-second timeout, set longer for long responses; (3) Error handling — handle mid-stream breaks gracefully, don't silently fail; (4) Testing — use curl -N http://localhost:8000/chat to test streaming. When not to use streaming: (A) structured output (JSON mode) doesn't need streaming, wait for completion then parse; (B) short responses (<100 tokens) — streaming adds complexity > benefits.

Q3: What's the safest API Key management approach? How to handle different environments (dev/staging/prod)?

Three-stage security upgrade. (1) Absolutely don't do: (A) hardcode in code, (B) commit to git, (C) place in frontend JavaScript (visible to users), (D) paste in Slack / email. (2) Basic approach (personal / small projects): (A) .env file + .gitignore — GEMINI_API_KEY=xxx in .env, code uses os.getenv(); (B) use python-dotenv — from dotenv import load_dotenv; load_dotenv(). (3) Advanced approach (teams / production): (A) GCP Secret Manager — from google.cloud import secretmanager; client.access_secret_version(...); (B) AWS Secrets Manager / Azure Key Vault — similar; (C) Environment variable injection — Kubernetes Secrets, Cloud Run env vars, GitHub Actions secrets. Managing across environments: (A) dev: personal API keys (one per person, lower quotas); (B) staging: shared test key with domain whitelist; (C) prod: production key in Secret Manager + rotation policy (90-day rotation); (D) CI/CD: GitHub Secrets, GCP Secret Manager — never hardcode. Leak emergency response: (1) Immediately revoke key (one-click in AI Studio / GCP console); (2) Rotate keys in all applications; (3) Check logs for abnormal usage; (4) Clean git history (use BFG Repo-Cleaner). Google auto-scans GitHub and disables detected Gemini API keys, but don't rely on this alone.

Q4: Got hit with rate limits — what's the strategy for handling 429 errors?

Exponential backoff + Retry is the gold standard. Gemini API rate limits: (1) Free tier: 15 req/min, 1500 req/day (Flash); (2) Paid Tier 1: 1,000 req/min; (3) Paid Tiers 2–5: 10,000–2,000,000 req/min, auto-upgraded based on credit and usage. Python implementation: from tenacity import retry, stop_after_attempt, wait_exponential; @retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=2, max=60)) def call_gemini(): response = model.generate_content(...); return response. Or Google's native google.api_core.retry. Prevention strategies: (1) Caching identical queries — store in Redis for 60 minutes; (2) Batch API — for non-real-time tasks, Batch API is 50% cheaper with no rate limits; (3) Queue requests — use Celery / RQ for unified scheduling; (4) Multi-project distribution — each GCP project has independent quota, linearly scales (but requires payment); (5) Upgrade Tier — sustained usage auto-upgrades; or file a request to accelerate. Monitoring: set Cloud Monitoring alerts at 80% quota threshold to add capacity proactively.

Q5: For long documents (100-page PDFs, 1-hour videos), can Gemini's context really handle it?

Yes, but watch cost and strategy. Gemini 2.0 Pro natively supports 2M token context, equivalent to approximately 1.5M Chinese characters / 800 pages / 2 hours of video. Real-world examples: (1) 100-page PDF processing: ~40,000 tokens, using genai.upload_file('report.pdf') to upload, then reference in prompt. Cost: Flash ~$0.003, Pro ~$0.05 per query. (2) 1-hour video analysis: ~500,000 tokens (depending on resolution), genai.upload_file('video.mp4'). Cost: Flash ~$0.04, Pro ~$0.6 per query. (3) Full text of 10 books: if each is 100K tokens, 10 books = 1M tokens, feasible to include all at once. Practical strategies: (1) Context Caching saves 75% — if querying the same long document multiple times, enable cached_content feature; subsequent queries cost only 25%; (2) Don't blindly stuff full text — chunking + retrieval (RAG) is sometimes cheaper for specific use cases; (3) Chunk summarize then analyze — summarize each chapter first, then analyze overall; essential for documents >2M tokens; (4) File API reuse — upload once, reference multiple times without re-upload until expiration; (5) Watch token count — model.count_tokens(prompt) estimates cost. Limitations: (A) uploaded files expire after 48 hours; (B) single file max 2GB; (C) Flash context up to 1M, Pro up to 2M.

---

References

1. Google AI for Developers -- Gemini API Quickstart with Python (https://ai.google.dev/gemini-api/docs/quickstart?lang=python)
2. google-generativeai PyPI package (https://pypi.org/project/google-generativeai/)
3. Gemini API Cookbook -- GitHub (https://github.com/google-gemini/cookbook)
4. Google AI Studio (https://aistudio.google.com)

---