google-gemini-api

# Google Gemini API - Complete Guide

**Package**: @google/genai@1.27.0 (⚠️ NOT @google/generative-ai)
**Last Updated**: 2025-11-21

---

## ⚠️ CRITICAL SDK MIGRATION WARNING

**DEPRECATED SDK**: `@google/generative-ai` (sunset November 30, 2025)
**CURRENT SDK**: `@google/genai` v1.27+

**If you see code using `@google/generative-ai`, it's outdated!**

**Load `references/sdk-migration-guide.md` for complete migration steps.**

---

## Quick Start

### Installation

**✅ CORRECT SDK:**
```bash
bun add @google/genai@1.27.0
```

**❌ WRONG (DEPRECATED):**
```bash
bun add @google/generative-ai  # DO NOT USE!
```

### Environment Setup

```bash
export GEMINI_API_KEY="your-api-key"
```

### First Text Generation

```typescript
import { GoogleGenAI } from '@google/genai';

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

const response = await ai.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Explain quantum computing in simple terms'
});

console.log(response.text);
```

**See Full Template**: `templates/basic-usage.ts`

---

## Current Models (2025)

### gemini-2.5-flash ⭐ RECOMMENDED

- **Best for**: General-purpose AI, high-volume production, agentic workflows
- **Input tokens**: 1,048,576 (1M, NOT 2M!)
- **Output tokens**: 65,536
- **Rate limit (free)**: 10 RPM, 250k TPM
- **Cost**: Input $0.075/1M tokens, Output $0.30/1M tokens
- **Features**: Thinking mode, function calling, multimodal, streaming

### gemini-2.5-pro

- **Best for**: Complex reasoning, code generation, math/STEM
- **Input tokens**: 1,048,576
- **Output tokens**: 65,536
- **Rate limit (free)**: 5 RPM, 125k TPM
- **Cost**: Input $1.25/1M tokens, Output $5/1M tokens

### gemini-2.5-flash-lite

- **Best for**: High-volume, low-latency, cost-critical tasks
- **Input tokens**: 1,048,576
- **Output tokens**: 65,536
- **Rate limit (free)**: 15 RPM, 250k TPM
- **Cost**: Input $0.01/1M tokens, Output $0.04/1M tokens
- **⚠️ Limitation**: NO function calling or code executio