Gemini API — Build AI Apps with Google AI

Introduction

The Gemini API provides programmatic access to Google's AI models with unique capabilities like real-time web search, 1M token context, and tight integration with Google Cloud services. This guide covers practical implementation, from basic setup to production applications with advanced features like function calling and batch processing.

API Setup
Basic API Call
Advanced Parameters
Multi-Modal Input
Streaming Responses
Conversation Management
Web Search Integration
File Upload and Analysis
Function Calling (Tool Use)
Error Handling
Batch Processing
Cost Optimization
Production Checklist
Practical Example: Customer Support Bot
Conclusion
FAQ

API Setup

Get started quickly:

pip install google-generativeai

Create and manage API keys:

import google.generativeai as genai

# Method 1: Environment variable
import os
os.environ['GOOGLE_API_KEY'] = 'YOUR_API_KEY'
genai.configure(api_key=os.environ['GOOGLE_API_KEY'])

# Method 2: Direct configuration
genai.configure(api_key="AIzaSy...")

# List available models
for model in genai.list_models():
    print(f"{model.name}: {model.display_name}")

Basic API Call

Simple request:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

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

response = model.generate_content(
    "Write a Python function to check if a number is prime"
)

print(response.text)

Advanced Parameters

Control model behavior:

response = model.generate_content(
    "Explain quantum physics",
    generation_config=genai.types.GenerationConfig(
        candidate_count=1,  # Number of response variants
        max_output_tokens=500,  # Response length
        temperature=0.7,  # Creativity (0-2)
        top_p=0.95,  # Nucleus sampling
        top_k=40,  # Top-K sampling
    ),
    safety_settings=[
        {
            "category": genai.types.HarmCategory.HARM_CATEGORY_UNSPECIFIED,
            "threshold": genai.types.HarmBlockThreshold.BLOCK_NONE,
        }
    ]
)

Combine text and images:

from PIL import Image
import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

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

# Load image
image = Image.open('screenshot.png')

# Analyze image with text
response = model.generate_content([
    "Describe the key elements and identify any UX issues",
    image
])

print(response.text)

Streaming Responses

Stream tokens for real-time feedback:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

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

# Enable streaming
response = model.generate_content(
    "Write a technical blog post about machine learning",
    stream=True
)

# Process tokens as they arrive
for chunk in response:
    if chunk.text:
        print(chunk.text, end="", flush=True)
print()

Conversation Management

Maintain multi-turn conversations:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

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

# Start conversation
chat = model.start_chat(history=[])

# Multi-turn conversation
messages = [
    "What is machine learning?",
    "Explain supervised learning",
    "Give me an example in Python"
]

for message in messages:
    response = chat.send_message(message)
    print(f"You: {message}")
    print(f"Gemini: {response.text}\n")

Web Search Integration

Access real-time information:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

# Enable Google Search
model = genai.GenerativeModel(
    'gemini-2.0-flash',
    tools=[genai.Tool(google_search_retrieval=genai.GoogleSearchRetrieval())]
)

response = model.generate_content(
    "What were the top news stories about AI this week? Provide current links."
)

print(response.text)

# Access citations
if hasattr(response, 'grounding_attributions'):
    for attribution in response.grounding_attributions:
        print(f"Source: {attribution}")

File Upload and Analysis

Upload files for analysis:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

# Upload file
uploaded_file = genai.upload_file(
    path="document.pdf",
    mime_type="application/pdf"
)

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

# Analyze uploaded file
response = model.generate_content([
    "Summarize this document and identify key points",
    uploaded_file
])

print(response.text)

# Clean up
genai.delete_file(uploaded_file.name)

Function Calling (Tool Use)

Define functions for Gemini to call:

import google.generativeai as genai
import json

genai.configure(api_key="YOUR_API_KEY")

# Define tools
tools = [
    {
        "function_declarations": [
            {
                "name": "search_product",
                "description": "Search for a product in the catalog",
                "parameters": {
                    "type": "OBJECT",
                    "properties": {
                        "query": {
                            "type": "STRING",
                            "description": "Product search term"
                        },
                        "max_results": {
                            "type": "NUMBER",
                            "description": "Maximum results"
                        }
                    },
                    "required": ["query"]
                }
            },
            {
                "name": "get_product_details",
                "description": "Get detailed info about a product",
                "parameters": {
                    "type": "OBJECT",
                    "properties": {
                        "product_id": {
                            "type": "STRING",
                            "description": "Product ID"
                        }
                    },
                    "required": ["product_id"]
                }
            }
        ]
    }
]

model = genai.GenerativeModel(
    'gemini-2.0-flash',
    tools=tools
)

def search_product(query, max_results=5):
    """Simulate product search"""
    products = {
        "laptop": [{"id": "p1", "name": "Dell XPS 13", "price": "$1200"}],
        "mouse": [{"id": "p2", "name": "Logitech MX", "price": "$99"}]
    }
    return products.get(query.lower(), [])[:max_results]

def get_product_details(product_id):
    """Get product details"""
    details = {
        "p1": {"name": "Dell XPS 13", "cpu": "Intel i7", "ram": "16GB", "price": "$1200"},
        "p2": {"name": "Logitech MX", "dpi": "4000", "wireless": True, "price": "$99"}
    }
    return details.get(product_id, {})

# Conversation with tool use
response = model.generate_content("Find me a good laptop")

# Process tool calls
for part in response.parts:
    if hasattr(part, 'function_call'):
        tool_call = part.function_call

        if tool_call.name == "search_product":
            result = search_product(**tool_call.args)
        elif tool_call.name == "get_product_details":
            result = get_product_details(**tool_call.args)

        print(f"Function: {tool_call.name}")
        print(f"Result: {json.dumps(result)}")

Error Handling

Robust error handling for production:

import google.generativeai as genai
import time

def call_gemini_with_retry(
    prompt,
    max_retries=3,
    backoff_factor=2
):
    """Call Gemini with retry logic"""
    genai.configure(api_key="YOUR_API_KEY")

    for attempt in range(max_retries):
        try:
            model = genai.GenerativeModel('gemini-2.0-flash')
            response = model.generate_content(prompt)
            return response

        except genai.RateLimitError:
            if attempt < max_retries - 1:
                wait_time = backoff_factor ** attempt
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
            else:
                raise

        except Exception as e:
            print(f"Error: {str(e)}")
            raise

    return None

Batch Processing

Process multiple requests efficiently:

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

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

# List of requests
requests = [
    "Explain machine learning",
    "What is deep learning?",
    "Define neural networks",
]

# Process in batch
responses = []

for prompt in requests:
    response = model.generate_content(prompt)
    responses.append({
        "prompt": prompt,
        "response": response.text
    })

# Use results
for item in responses:
    print(f"Q: {item['prompt']}")
    print(f"A: {item['response']}\n")

Cost Optimization

Strategies to manage costs:

def optimize_for_cost(prompt, model_choice="flash"):
    """Choose model based on complexity"""
    genai.configure(api_key="YOUR_API_KEY")

    # Use Flash for simple tasks (faster, cheaper)
    if len(prompt) < 100 and "complex" not in prompt.lower():
        model_name = 'gemini-2.0-flash'
    else:
        model_name = 'gemini-1.5-pro'

    model = genai.GenerativeModel(model_name)

    return model.generate_content(
        prompt,
        generation_config=genai.types.GenerationConfig(
            max_output_tokens=500,  # Limit output tokens
            temperature=0.5,  # Lower temperature = faster
        )
    )

Production Checklist

Before deploying to production:

# 1. Secure API key
import os
api_key = os.environ.get('GOOGLE_API_KEY')
if not api_key:
    raise ValueError("GOOGLE_API_KEY not set")

# 2. Implement rate limiting
from ratelimit import limits, sleep_and_retry
import time

@sleep_and_retry
@limits(calls=60, period=60)  # 60 calls per minute
def call_gemini_limited(prompt):
    genai.configure(api_key=api_key)
    model = genai.GenerativeModel('gemini-2.0-flash')
    return model.generate_content(prompt)

# 3. Add logging
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

logger.info(f"API call with {len(prompt)} characters")

# 4. Set timeouts
genai.configure(
    api_key=api_key,
    transport_method="requests"
)

# 5. Monitor usage
def log_usage(response):
    """Track token usage for billing"""
    usage = response.usage_metadata
    logger.info(
        f"Tokens: input={usage.prompt_token_count}, "
        f"output={usage.candidates_token_count}"
    )

Practical Example: Customer Support Bot

import google.generativeai as genai

genai.configure(api_key="YOUR_API_KEY")

class SupportBot:
    def __init__(self):
        self.model = genai.GenerativeModel('gemini-2.0-flash')
        self.chat = None

    def start_session(self, customer_info):
        """Start a new support session"""
        system_prompt = f"""You are a helpful customer support agent.
        Customer: {customer_info}

        Help resolve their issues quickly and professionally.
        If you need to search for current info, use available tools.
        """

        self.chat = self.model.start_chat()
        return system_prompt

    def respond(self, customer_message):
        """Get response to customer message"""
        response = self.chat.send_message(customer_message)
        return response.text

# Usage
bot = SupportBot()
bot.start_session("Premium customer experiencing billing issue")
response = bot.respond("I was charged twice this month")
print(response)

Conclusion

The Gemini API offers a compelling alternative to ChatGPT and Claude, particularly for applications requiring real-time information, visual analysis, and Google Cloud integration. Its competitive pricing and unique features make it worth evaluating for your use case.

FAQ

Q: Is Gemini API free? A: Google AI Studio offers free tier. Production requires payment on a pay-as-you-go model.

Q: How does Gemini compare to GPT-4? A: Gemini 2.0 Flash is faster and cheaper. GPT-4 has better reasoning. Choose based on your needs.

Q: Can I use Gemini for enterprise applications? A: Yes, through Vertex AI on Google Cloud with enterprise support and SLAs.