gemini-api

# Gemini API

Build applications with the Google Gemini API and SDKs.

## When to Use

- Building applications that call the Gemini API
- Code imports `google.generativeai` (Python) or `@google/generative-ai` (TypeScript)
- User asks about Gemini API patterns, function calling, streaming, or vision
- Implementing agent workflows with the Gemini API
- Optimizing API costs, token usage, or latency

## Model Selection

| Model | ID | Best For |
|-------|-----|----------|
| Pro 2.5 | `gemini-2.5-pro` | Complex reasoning, architecture, research |
| Flash 2.5 | `gemini-2.5-flash` | Balanced coding, most development tasks |
| Flash Lite 2.5 | `gemini-2.5-flash-lite` | Fast responses, high-volume, cost-sensitive |

Default to Flash 2.5 unless the task requires deep reasoning (Pro) or speed/cost optimization (Flash Lite). For production, prefer pinned snapshot IDs over aliases.

## Python SDK

### Installation

```bash
pip install google-generativeai
```

### Basic Message

```python
import os
import google.generativeai as genai

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

model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content("Explain async/await in Python")
print(response.text)
```

### Streaming

```python
model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content(
    "Write a haiku about coding",
    stream=True,
)
for chunk in response:
    print(chunk.text, end="", flush=True)
```

### System Instruction

```python
model = genai.GenerativeModel(
    "gemini-2.5-flash",
    system_instruction="You are a senior Python developer. Be concise.",
)
response = model.generate_content("Review this function")
```

## TypeScript SDK

### Installation

```bash
npm install @google/generative-ai
```

### Basic Message

```typescript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });

const result = await model.generateContent("Explain async/await in TypeScript");
console.log(result.response.text());
```

### Streaming

```typescript
const model = genAI.getGenerativeModel({ model: "gemini-2.5-flash" });

const result = await model.generateContentStream("Write a haiku");

for await (const chunk of result.stream) {
  const text = chunk.text();
  process.stdout.write(text);
}
```

## Function Calling (Tool Use)

Define tools and let Gemini call them:

```python
def get_weather(location: str, unit: str = "celsius") -> dict:
    """Get current weather for a location."""
    # Your implementation here
    return {"temp": 18, "unit": unit, "location": location}

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

chat = model.start_chat(enable_automatic_function_calling=True)
response = chat.send_message("What's the weather in SF?")
print(response.text)
```

For manual function calling (more control):

```python
import google.generativeai as genai
from google.generativeai.types import FunctionDeclaration, Tool

weather_func = FunctionDeclaration(
    name="get_weather",
    description="Get current weather for a location",
    parameters={
        "type": "object",
        "properties": {
            "location": {"type": "string", "description": "City name"},
            "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
        },
        "required": ["location"],
    },
)

tool = Tool(function_declarations=[weather_func])
model = genai.GenerativeModel("gemini-2.5-flash", tools=[tool])

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

# Check for function call in response
for part in response.parts:
    if fn := part.function_call:
        # Execute the function with fn.args
        result = get_weather(**dict(fn.args))
        # Send result back
        response = chat.send_message(
            genai.protos.Content(
                parts=[genai.protos.Part(
                    function_response=genai.protos.FunctionResponse(
                        name=fn.name,
                        response={"result": result},
                    )
                )]
            )
        )
```

## Vision

Send images for analysis:

```python
import PIL.Image

image = PIL.Image.open("diagram.png")

model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content(
    ["Describe this diagram", image]
)
print(response.text)
```

Or from raw bytes:

```python
with open("diagram.png", "rb") as f:
    image_data = f.read()

response = model.generate_content([
    "Describe this diagram",
    {"mime_type": "image/png", "data": image_data},
])
```

## Thinking (Extended Reasoning)

For complex reasoning tasks, enable thinking in the generation config:

```python
model = genai.GenerativeModel("gemini-2.5-flash")
response = model.generate_content(
    "Solve this math problem step by step...",
    generation_config=genai.GenerationConfig(
        thinking_config=genai.types.ThinkingConfig(
            thinking_budget=10000,
        ),
    ),
)

for part in response.candidates[0].content.parts:
    if part.thought:
        print(f"Thinking: {part.text}")
    else:
        print(f"Answer: {part.text}")
```

## Context Caching

Cache large contexts to reduce costs on repeated requests:

```python
from google.generativeai import caching
import datetime

cache = caching.CachedContent.create(
    model="gemini-2.5-flash",
    display_name="my-cached-context",
    system_instruction="You are an expert analyst.",
    contents=[large_context_text],
    ttl=datetime.timedelta(minutes=30),
)

# Use the cached content with a model
model = genai.GenerativeModel.from_cached_content(cache)
response = model.generate_content("Question about the cached context")
```

## Batch Requests

Process multiple requests efficiently:

```python
model = genai.GenerativeModel("gemini-2.5-flash")

# Use asyncio for concurrent requests
import asyncio

async def process_batch(prompts: list[str]) -> list[str]:
    """Process multiple prompts concurrently."""
    async_model = genai.GenerativeModel("gemini-2.5-flash")
    tasks = [
        async_model.generate_content_async(prompt)
        for prompt in prompts
    ]
    responses = await asyncio.gather(*tasks)
    return [r.text for r in responses]

# Run the batch
results = asyncio.run(process_batch(prompts))
```

## Agent Loop

Build multi-step agents with function calling:

```python
import google.generativeai as genai

# Define tools as function declarations
tools = [
    genai.protos.Tool(function_declarations=[
        genai.protos.FunctionDeclaration(
            name="search_codebase",
            description="Search the codebase for relevant code",
            parameters={
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        )
    ])
]

model = genai.GenerativeModel("gemini-2.5-flash", tools=tools)
chat = model.start_chat()

response = chat.send_message("Review the auth module for security issues")

# Agentic loop: keep processing function calls until the model stops
while response.candidates[0].finish_reason.name == "STOP" and any(
    part.function_call for part in response.parts
):
    for part in response.parts:
        if fn := part.function_call:
            result = execute_tool(fn.name, dict(fn.args))
            response = chat.send_message(
                genai.protos.Content(
                    parts=[genai.protos.Part(
                        function_response=genai.protos.FunctionResponse(
                            name=fn.name,
                            response={"result": result},
                        )
                    )]
                )
            )

print(response.text)
```

## Cost Optimization

| Strategy | Savings | When to Use |
|----------|---------|-------------|
| Context caching | Up to 75% on cached tokens | Repeated system prompts or context |
| Batch with async | Variable | Non-time-sensitive bulk processing |
| Flash Lite instead of Flash | ~75% | Simple tasks, classification, extraction |
| Shorter max_output_tokens | Variable | When you know output will be short |
| Streaming | None (same cost) | Better UX, same price |

## Error Handling

```python
import time

from google.api_core.exceptions import (
    ResourceExhausted,
    ServiceUnavailable,
    GoogleAPIError,
)

try:
    response = model.generate_content(...)
except ResourceExhausted:
    # Rate limited, back off and retry
    time.sleep(60)
except ServiceUnavailable:
    # Service issue, retry with backoff
    pass
except GoogleAPIError as e:
    print(f"API error: {e.message}")
```

## Environment Setup

```bash
# Required
export GEMINI_API_KEY="your-api-key-here"

# Optional: set default model
export GEMINI_MODEL="gemini-2.5-flash"
```

Never hardcode API keys. Always use environment variables.