feat: NanoBanana Pro 2 support (#320)

.changeset/five-parts-leave.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-gemini': minor
+---
+
+- Add NanoBanana native image generation with up to 4K image output, routing all gemini-\* native image models through generateContent API
+- Fix SDK property names (imageGenerationConfig → imageConfig, outputImageSize → imageSize) and rename NanoBanana types to GeminiNativeImage
+- Add Gemini 3.1 Pro model support for text generation

docs/adapters/fal.md

@@ -5,7 +5,7 @@ id: fal-adapter
 
 The fal.ai adapter provides access to 600+ models on the fal.ai platform for image generation and video generation. Unlike text-focused adapters, the fal adapter is **media-focused** — it supports `generateImage()` and `generateVideo()` but does not support `chat()` or tools. Audio and speech support are coming soon.
 
-For a full working example, see the [fal.ai example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-fal).
+For a full working example, see the [fal.ai example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-media).
 
 ## Installation
 
@@ -79,7 +79,7 @@ const proxiedAdapter = falImage("fal-ai/flux/dev", {
 
 ## Example: Image Generation
 
-From the [fal.ai example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-fal):
+From the [fal.ai example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-media):
 
 ```typescript
 import { generateImage } from "@tanstack/ai";
@@ -155,7 +155,7 @@ import { falVideo } from "@tanstack/ai-fal";
 
 ## Example: Text-to-Video
 
-From the [fal.ai example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-fal):
+From the [fal.ai example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-media):
 
 ```typescript
 import { generateVideo, getVideoJobStatus } from "@tanstack/ai";

docs/adapters/gemini.md

@@ -4,7 +4,9 @@ id: gemini-adapter
 order: 3
 ---
 
-The Google Gemini adapter provides access to Google's Gemini models, including text generation, image generation with Imagen, and experimental text-to-speech.
+The Google Gemini adapter provides access to Google's Gemini models, including text generation, image generation with both Imagen and Gemini native image models (NanoBanana), and experimental text-to-speech.
+
+For a full working example with image generation, see the [media generation example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-media).
 
 ## Installation
 
@@ -158,26 +160,91 @@ console.log(result.summary);
 
 ## Image Generation
 
-Generate images with Imagen:
+The Gemini adapter supports two types of image generation:
+
+- **Gemini native image models** (NanoBanana) — Use the `generateContent` API with models like `gemini-3.1-flash-image-preview`. These support extended resolution tiers (1K, 2K, 4K) and aspect ratio control.
+- **Imagen models** — Use the `generateImages` API with models like `imagen-4.0-generate-001`. These are dedicated image generation models with WIDTHxHEIGHT sizing.
+
+The adapter automatically routes to the correct API based on the model name — models starting with `gemini-` use `generateContent`, while `imagen-` models use `generateImages`.
+
+### Example: Gemini Native Image Generation (NanoBanana)
+
+From the [media generation example app](https://github.com/TanStack/ai/tree/main/examples/ts-react-media):
+
+```typescript
+import { generateImage } from "@tanstack/ai";
+import { geminiImage } from "@tanstack/ai-gemini";
+
+const result = await generateImage({
+  adapter: geminiImage("gemini-3.1-flash-image-preview"),
+  prompt: "A futuristic cityscape at sunset",
+  numberOfImages: 1,
+  size: "16:9_4K",
+});
+
+console.log(result.images);
+```
+
+### Example: Imagen
 
 ```typescript
 import { generateImage } from "@tanstack/ai";
 import { geminiImage } from "@tanstack/ai-gemini";
 
 const result = await generateImage({
-  adapter: geminiImage("imagen-3.0-generate-002"),
+  adapter: geminiImage("imagen-4.0-generate-001"),
   prompt: "A futuristic cityscape at sunset",
   numberOfImages: 1,
 });
 
 console.log(result.images);
 ```
 
+### Image Size Options
+
+#### Gemini Native Models (NanoBanana)
+
+Gemini native image models use a template literal size format combining aspect ratio and resolution tier:
+
+```typescript
+// Format: "aspectRatio_resolution"
+size: "16:9_4K"
+size: "1:1_2K"
+size: "9:16_1K"
+```
+
+| Component | Values |
+|-----------|--------|
+| Aspect Ratio | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9` |
+| Resolution | `1K`, `2K`, `4K` |
+
+#### Imagen Models
+
+Imagen models use WIDTHxHEIGHT format, which maps to aspect ratios internally:
+
+| Size | Aspect Ratio |
+|------|-------------|
+| `1024x1024` | 1:1 |
+| `1920x1080` | 16:9 |
+| `1080x1920` | 9:16 |
+
+Alternatively, you can specify the aspect ratio directly in Model Options:
+
+```typescript
+const result = await generateImage({
+  adapter: geminiImage("imagen-4.0-generate-001"),
+  prompt: "A landscape photo",
+  modelOptions: {
+    aspectRatio: "16:9",
+  },
+});
+```
+
 ### Image Model Options
 
 ```typescript
 const result = await generateImage({
-  adapter: geminiImage("imagen-3.0-generate-002"),
+  adapter: geminiImage("imagen-4.0-generate-001"),
   prompt: "...",
   modelOptions: {
     aspectRatio: "16:9", // "1:1" | "3:4" | "4:3" | "9:16" | "16:9"
@@ -221,6 +288,30 @@ GOOGLE_API_KEY=your-api-key-here
 2. Create a new API key
 3. Add it to your environment variables
 
+## Popular Image Models
+
+### Gemini Native Image Models (NanoBanana)
+
+These models use the `generateContent` API and support resolution tiers (1K, 2K, 4K).
+
+| Model | Description |
+|-------|-------------|
+| `gemini-3.1-flash-image-preview` | Latest and fastest Gemini native image generation |
+| `gemini-3-pro-image-preview` | Higher quality Gemini native image generation |
+| `gemini-2.5-flash-image` | Gemini 2.5 Flash with image generation |
+| `gemini-2.0-flash-preview-image-generation` | Gemini 2.0 Flash image generation |
+
+### Imagen Models
+
+These models use the dedicated `generateImages` API.
+
+| Model | Description |
+|-------|-------------|
+| `imagen-4.0-ultra-generate-001` | Best quality Imagen image generation |
+| `imagen-4.0-generate-001` | High quality Imagen image generation |
+| `imagen-4.0-fast-generate-001` | Fast Imagen image generation |
+| `imagen-3.0-generate-002` | Imagen 3 image generation |
+
 ## API Reference
 
 ### `geminiText(config?)`
@@ -252,15 +343,26 @@ Creates a Gemini summarization adapter with an explicit API key.
 
 **Returns:** A Gemini summarize adapter instance.
 
-### `geminiImage(config?)`
+### `geminiImage(model, config?)`
+
+Creates a Gemini image adapter using environment variables. Automatically routes to the correct API based on model name — `gemini-*` models use `generateContent`, `imagen-*` models use `generateImages`.
+
+**Parameters:**
 
-Creates a Gemini image generation adapter using environment variables.
+- `model` - The model name (e.g., `"gemini-3.1-flash-image-preview"` or `"imagen-4.0-generate-001"`)
+- `config.baseURL?` - Custom base URL (optional)
 
 **Returns:** A Gemini image adapter instance.
 
-### `createGeminiImage(apiKey, config?)`
+### `createGeminiImage(model, apiKey, config?)`
+
+Creates a Gemini image adapter with an explicit API key.
 
-Creates a Gemini image generation adapter with an explicit API key.
+**Parameters:**
+
+- `model` - The model name
+- `apiKey` - Your Google API key
+- `config.baseURL?` - Custom base URL (optional)
 
 **Returns:** A Gemini image adapter instance.
 
@@ -278,6 +380,8 @@ Creates a Gemini TTS adapter with an explicit API key.
 
 ## Next Steps
 
+- [Image Generation Guide](../guides/image-generation) - Learn more about image generation
+- [Media Generation Example](https://github.com/TanStack/ai/tree/main/examples/ts-react-media) - Full working example with Gemini and fal.ai
 - [Getting Started](../getting-started/quick-start) - Learn the basics
 - [Tools Guide](../guides/tools) - Learn about tools
 - [Other Adapters](./openai) - Explore other providers

docs/guides/image-generation.md

@@ -13,7 +13,8 @@ TanStack AI provides support for image generation through dedicated image adapte
 Image generation is handled by image adapters that follow the same tree-shakeable architecture as other adapters in TanStack AI. The image adapters support:
 
 - **OpenAI**: DALL-E 2, DALL-E 3, GPT-Image-1, and GPT-Image-1-Mini models
-- **Gemini**: Imagen 3 and Imagen 4 models
+- **Gemini**: Gemini native image models (NanoBanana) and Imagen 3/4 models
+- **fal.ai**: 600+ models including Nano Banana Pro, FLUX, and more
 
 ## Basic Usage
 
@@ -37,16 +38,22 @@ console.log(result.images[0].url) // URL to the generated image
 
 ### Gemini Image Generation
 
+Gemini supports two types of image generation: Gemini native models (NanoBanana) and Imagen models. The adapter automatically routes to the correct API based on the model name.
+
 ```typescript
 import { generateImage } from '@tanstack/ai'
 import { geminiImage } from '@tanstack/ai-gemini'
 
-// Create an image adapter (uses GOOGLE_API_KEY from environment)
-const adapter = geminiImage()
-
-// Generate an image
+// Gemini native model (NanoBanana) — uses generateContent API
 const result = await generateImage({
-  adapter: geminiImage('imagen-3.0-generate-002'),
+  adapter: geminiImage('gemini-3.1-flash-image-preview'),
+  prompt: 'A futuristic cityscape at night',
+  size: '16:9_4K',
+})
+
+// Imagen model — uses generateImages API
+const result2 = await generateImage({
+  adapter: geminiImage('imagen-4.0-generate-001'),
   prompt: 'A futuristic cityscape at night',
 })
 
@@ -78,9 +85,24 @@ All image adapters support these common options:
 | `dall-e-3` | `1024x1024`, `1792x1024`, `1024x1792` |
 | `dall-e-2` | `256x256`, `512x512`, `1024x1024` |
 
-#### Gemini Models
+#### Gemini Native Models (NanoBanana)
 
-Gemini uses aspect ratios internally, but TanStack AI accepts WIDTHxHEIGHT format and converts them:
+Gemini native image models use a template literal size format: `"aspectRatio_resolution"`.
+
+| Aspect Ratios | Resolutions |
+|---------------|-------------|
+| `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `9:16`, `16:9`, `21:9` | `1K`, `2K`, `4K` |
+
+```typescript
+// Examples
+size: "16:9_4K"   // Widescreen at 4K resolution
+size: "1:1_2K"    // Square at 2K resolution
+size: "9:16_1K"   // Portrait at 1K resolution
+```
+
+#### Gemini Imagen Models
+
+Imagen models accept WIDTHxHEIGHT format, which maps to aspect ratios internally:
 
 | Size | Aspect Ratio |
 |------|-------------|
@@ -134,7 +156,7 @@ const result = await generateImage({
 })
 ```
 
-### Gemini Model Options
+### Gemini Imagen Model Options
 
 ```typescript
 const result = await generateImage({
@@ -150,6 +172,18 @@ const result = await generateImage({
 })
 ```
 
+### Gemini Native Model Options (NanoBanana)
+
+Gemini native image models accept `GenerateContentConfig` options directly in `modelOptions`:
+
+```typescript
+const result = await generateImage({
+  adapter: geminiImage('gemini-3.1-flash-image-preview'),
+  prompt: 'A beautiful garden',
+  size: '16:9_4K',
+})
+```
+
 ## Response Format
 
 The image generation result includes:
@@ -184,14 +218,23 @@ interface GeneratedImage {
 | `dall-e-3` | 1 |
 | `dall-e-2` | 1-10 |
 
-### Gemini Models
+### Gemini Native Models (NanoBanana)
+
+| Model | Description |
+|-------|-------------|
+| `gemini-3.1-flash-image-preview` | Latest and fastest Gemini native image generation |
+| `gemini-3-pro-image-preview` | Higher quality Gemini native image generation |
+| `gemini-2.5-flash-image` | Gemini 2.5 Flash with image generation |
+| `gemini-2.0-flash-preview-image-generation` | Gemini 2.0 Flash image generation |
+
+### Gemini Imagen Models
 
 | Model | Images per Request |
 |-------|-------------------|
-| `imagen-3.0-generate-002` | 1-4 |
+| `imagen-4.0-ultra-generate-001` | 1-4 |
 | `imagen-4.0-generate-001` | 1-4 |
 | `imagen-4.0-fast-generate-001` | 1-4 |
-| `imagen-4.0-ultra-generate-001` | 1-4 |
+| `imagen-3.0-generate-002` | 1-4 |
 
 ## Error Handling
 
@@ -216,7 +259,7 @@ try {
 The image adapters use the same environment variables as the text adapters:
 
 - **OpenAI**: `OPENAI_API_KEY`
-- **Gemini**: `GOOGLE_API_KEY` or `GEMINI_API_KEY`
+- **Gemini** (including NanoBanana): `GOOGLE_API_KEY` or `GEMINI_API_KEY`
 
 ## Explicit API Keys
 

examples/ts-react-fal/.env.example → examples/ts-react-media/.env.example

@@ -1,4 +1,7 @@
-# Duplicate the .env.example file and rename it to .env.local, then add your FAL_KEY.
+# Duplicate the .env.example file and rename it to .env.local, then add your API keys.
 
 # Sign up for an account at https://fal.ai, and add $20 of credits to your account to get started.
 FAL_KEY=
+
+# Get a Google API key at https://aistudio.google.com/apikey
+GOOGLE_API_KEY=

examples/ts-react-fal/package.json → examples/ts-react-media/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "ts-react-fal",
+  "name": "ts-react-media",
   "private": true,
   "type": "module",
   "scripts": {
@@ -13,6 +13,7 @@
     "@tailwindcss/vite": "^4.1.18",
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-fal": "workspace:*",
+    "@tanstack/ai-gemini": "workspace:*",
     "@tanstack/react-router": "^1.158.4",
     "@tanstack/react-start": "^1.159.0",
     "@tanstack/router-plugin": "^1.158.4",

examples/ts-react-fal/src/components/Header.tsx → examples/ts-react-media/src/components/Header.tsx

@@ -10,7 +10,7 @@ export default function Header() {
         </Link>
       </h1>
       <span className="ml-4 text-sm text-gray-400">
-        Image & Video Generation with fal.ai
+        Image & Video Generation
       </span>
     </header>
   )