Google Gemini API — SKILL.md

---
name: "Google Gemini API"
description: "Skill for Google Gemini API — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "dev"
agents: ["claude-code", "codex", "gemini"]
tags: ["google-gemini-api", "dev", "auto-generated"]
---

# Google Gemini API

---
name: Google Gemini API
description: Use this skill when you need to integrate Google's Gemini AI models for text generation, multimodal AI tasks, or building AI-powered applications. Essential for developers working with generative AI, content creation, code generation, or image analysis.
metadata:
  author: skynet
  version: 1.0.0
category: dev
---

# Google Gemini API

## Installation and Setup

### Install the SDK
```bash
# Python
pip install google-generativeai

# Node.js
npm install @google/generative-ai

# cURL (no installation needed)
curl --version
```

### API Key Setup
```bash
# Set environment variable
export GOOGLE_API_KEY="your-api-key-here"

# Or create .env file
echo "GOOGLE_API_KEY=your-api-key-here" > .env
```

## Quick Start Examples

### Python Basic Text Generation
```python
import google.generativeai as genai
import os

genai.configure(api_key=os.environ["GOOGLE_API_KEY"])
model = genai.GenerativeModel('gemini-pro')

response = model.generate_content("Write a haiku about coding")
print(response.text)
```

### Node.js Basic Implementation
```javascript
import { GoogleGenerativeAI } from "@google/generative-ai";

const genAI = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-pro" });

const result = await model.generateContent("Explain quantum computing");
console.log(result.response.text());
```

### cURL API Call
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: ${GOOGLE_API_KEY}" \
  -d '{
    "contents": [{
      "parts": [{"text": "Write a Python function to sort a list"}]
    }]
  }' \
  "https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent"
```

## Model Selection Decision Tree

```
Need to process images/video?
├─ Yes: Use gemini-pro-vision
│  └─ High quality images → gemini-1.5-pro
│  └─ General use → gemini-pro-vision
└─ No: Text only
   ├─ Complex reasoning needed → gemini-1.5-pro
   ├─ General use → gemini-pro
   └─ Fast/simple tasks → gemini-pro
```

## Common Workflows

### Multimodal Image Analysis
```python
import PIL.Image
import google.generativeai as genai

genai.configure(api_key=os.environ["GOOGLE_API_KEY"])
model = genai.GenerativeModel('gemini-pro-vision')

image = PIL.Image.open('image.jpg')
response = model.generate_content([
    "What's in this image? Describe it in detail.",
    image
])
print(response.text)
```

### Streaming Responses
```python
model = genai.GenerativeModel('gemini-pro')
response = model.generate_content(
    "Write a long story about space exploration",
    stream=True
)

for chunk in response:
    print(chunk.text, end='')
```

### Safety Settings Configuration
```python
safety_settings = [
    {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
]

model = genai.GenerativeModel(
    'gemini-pro',
    safety_settings=safety_settings
)
```

### Generation Configuration
```python
generation_config = genai.types.GenerationConfig(
    candidate_count=1,
    max_output_tokens=1000,
    temperature=0.7,
    top_p=0.8,
    top_k=40
)

response = model.generate_content(
    "Write creative marketing copy",
    generation_config=generation_config
)
```

## Advanced Features

### Chat Conversations
```python
model = genai.GenerativeModel('gemini-pro')
chat = model.start_chat(history=[])

response = chat.send_message("Hello, I'm working on a Python project")
print(response.text)

response = chat.send_message("Can you help me with error handling?")
print(response.text)
```

### Batch Processing
```python
prompts = [
    "Summarize the benefits of renewable energy",
    "Explain machine learning in simple terms",
    "Write a product description for a smartwatch"
]

responses = []
for prompt in prompts:
    response = model.generate_content(prompt)
    responses.append(response.text)
```

### Function Calling (Tool Use)
```python
def get_weather(location: str) -> str:
    return f"Weather in {location}: Sunny, 72°F"

tools = [get_weather]
model = genai.GenerativeModel('gemini-pro', tools=tools)

response = model.generate_content(
    "What's the weather like in New York?"
)
```

## Error Handling and Troubleshooting

### Common Errors and Solutions

**API Key Error:**
```
google.api_core.exceptions.Unauthenticated: 401 API key not valid
```
**Fix:**
```bash
# Verify API key is set
echo $GOOGLE_API_KEY
# Regenerate key in Google AI Studio
# Ensure key has proper permissions
```

**Rate Limit Error:**
```
google.api_core.exceptions.ResourceExhausted: 429 Quota exceeded
```
**Fix:**
```python
import time
from google.api_core import retry

@retry.Retry(predicate=retry.if_exception_type(Exception))
def generate_with_retry():
    return model.generate_content(prompt)
```

**Content Filtering:**
```
google.generativeai.types.BlockedPromptException: Prompt was blocked
```
**Fix:**
```python
# Adjust safety settings or rephrase prompt
safety_settings = [
    {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_ONLY_HIGH"
    }
]
```

### Validation Checks
```python
def validate_response(response):
    if not response.text:
        if response.prompt_feedback.block_reason:
            print(f"Blocked: {response.prompt_feedback.block_reason}")
            return False
    return True

response = model.generate_content("Your prompt here")
if validate_response(response):
    print(response.text)
```

## Performance Optimization

### Response Caching
```python
import functools

@functools.lru_cache(maxsize=100)
def cached_generate(prompt):
    return model.generate_content(prompt).text

# Use for repeated similar prompts
result = cached_generate("Explain photosynthesis")
```

### Async Operations (Node.js)
```javascript
async function batchGenerate(prompts) {
    const promises = prompts.map(prompt => 
        model.generateContent(prompt)
    );
    
    const results = await Promise.all(promises);
    return results.map(result => result.response.text());
}
```

## Monitoring and Logging

### Usage Tracking
```python
import logging

logging.basicConfig(level=logging.INFO)

def tracked_generate(prompt):
    start_time = time.time()
    try:
        response = model.generate_content(prompt)
        duration = time.time() - start_time
        logging.info(f"Generated {len(response.text)} chars in {duration:.2f}s")
        return response.text
    except Exception as e:
        logging.error(f"Generation failed: {e}")
        raise
```

## Best Practices

1. **Prompt Engineering**: Be specific and provide context
2. **Error Handling**: Always wrap API calls in try-catch blocks
3. **Rate Limiting**: Implement exponential backoff for retries
4. **Security**: Never hardcode API keys in source code
5. **Content Filtering**: Review safety settings for your use case
6. **Cost Management**: Monitor token usage and set limits