tooyoung:nano-banana-builder

Nano Banana Builder

Build production-ready web applications powered by Google's Nano Banana image generation APIs—creating everything from simple text-to-image generators to sophisticated iterative editors with multi-turn conversation.

---

CRITICAL: Exact Model Names

Use ONLY these exact model strings. Do not invent, guess, or add date suffixes.

Model String (use exactly)	Alias	Use Case
gemini-2.5-flash-image	Nano Banana	Fast iterations, drafts, high volume
gemini-3-pro-image-preview	Nano Banana Pro	Quality output, text rendering, 2K

Common mistakes to avoid:

• ❌ gemini-2.5-flash-preview-05-20 — wrong, date suffixes are for text models
• ❌ gemini-2.5-pro-image — wrong, 2.5 Pro doesn't do image generation
• ❌ gemini-3-flash-image — wrong, doesn't exist
• ❌ gemini-pro-vision — wrong, that's for image input, not generation

The only valid image generation models are gemini-2.5-flash-image and gemini-3-pro-image-preview.

---

SDK Version Requirements

Examples were tested against the versions below; verify the latest AI SDK and Google provider docs before upgrading:

Package	Minimum Version	Recommended
ai	3.4.0+	^4.0.0
@ai-sdk/google	0.0.52+	^1.0.0
@ai-sdk/react	0.0.62+	^1.0.0
next	14.0.0+	^15.0.0
react	18.2.0+	^19.0.0

Important notes:

• This skill uses Next.js App Router (not Pages Router)
• Server Actions require 'use server' directive
• All examples use TypeScript (recommended for type safety)

# Check your versions
npm list ai @ai-sdk/google @ai-sdk/react next

# Update to latest
npm update ai @ai-sdk/google @ai-sdk/react

Breaking changes to watch:

• result.files[0] structure may change between major versions
• providerOptions.google namespace for Gemini-specific configs
• useChat hook API from @ai-sdk/react

---

Philosophy: Conversational Image Generation

Nano Banana isn't just another image API—it's conversational by design. The core insight is that image generation works best as a dialogue, not a one-shot prompt.

Think of it as working with an AI art director:

• Iterative refinement → Build up images through conversation, not perfection in one prompt
• Context awareness → The model "remembers" previous generations and edits
• Natural language editing → Describe changes conversationally, not with parameters

Before Building, Ask

• What's the primary use case? Text-to-image generation? Image editing? Multi-image composition? Style transfer?
• Which model fits the need? Nano Banana (speed/iterations) or Nano Banana Pro (quality/complex prompts)?
• What's the user journey? Single generation? Iterative refinement? Gallery browsing?
• What are production constraints? Rate limits? Storage? Cost per image? User volume?

Core Principles

1. Conversation over configuration: Leverage Nano Banana's iterative editing rather than complex parameter UIs
2. Model selection matters: Use gemini-2.5-flash-image for speed/iterations, gemini-3-pro-image-preview for quality/complexity
3. State as conversation history: Track generations as chat messages to enable multi-turn editing
4. Rate limit awareness: Image generation has strict quotas—implement queuing and caching
5. Storage strategy: Store generated images (Vercel Blob/S3), not just inline base64

Model Selection Framework

Choose based on use case:

Use Case	Model	Why
Rapid iterations, drafts	gemini-2.5-flash-image	Fast (2-5s), lower cost per image
Final output, quality	gemini-3-pro-image-preview	Superior quality, thinking, text rendering
Text-heavy images	gemini-3-pro-image-preview	Best typography, 2K resolution
Multi-turn editing	Either	Both support conversational editing
High volume	gemini-2.5-flash-image	Lower cost, faster throughput

---

Quick Start

Basic Server Action

// app/actions/generate.ts
"use server";

import { google } from "@ai-sdk/google";
import { generateText } from "ai";

export async function generateImage(prompt: string) {
  const result = await generateText({
    model: google("gemini-2.5-flash-image"),
    prompt,
    providerOptions: {
      google: {
        responseModalities: ["IMAGE"],
        imageConfig: { aspectRatio: "16:9" },
      },
    },
  });

  return result.files[0]; // { base64, uint8Array, mediaType }
}

Client Component with useChat

// app/components/ImageGenerator.tsx
'use client'

import { useChat } from '@ai-sdk/react'

export function ImageGenerator() {
  const { append, messages, isLoading } = useChat({
    api: '/api/generate'
  })

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.parts?.map((part, i) =>
            part.type === 'image' && (
              <img key={i} src={part.url} alt="Generated" />
            )
          )}
        </div>
      ))}

      <button
        disabled={isLoading}
        onClick={() => append({
          role: 'user',
          content: 'A futuristic cityscape at dusk'
        })}
      >
        Generate
      </button>
    </div>
  )
}

---

Prompt Engineering

For prompt structure, quality boosters, enhancer utility, negative prompts, and use-case templates, see references/prompt-engineering.md.

---

Advanced Implementation

For complete implementations including:

• Server Actions with model selection, storage, and error handling
• API Routes with streaming responses
• Client Components with iterative editing and galleries
• Advanced Patterns like multi-image composition and batch generation

See references/advanced-patterns.md

---

Safety Settings & Content Moderation

For Gemini safety settings, pre-generation prompt filtering, safety block handling, and production best practices, see references/safety-settings.md.

---

Configuration & Operations

For detailed configuration and operational concerns:

• Provider Options (responseModalities, imageConfig, thinkingConfig)
• Storage Strategy (Vercel Blob, S3/R2 implementations)
• Rate Limiting (Upstash Redis patterns, quota management)
• Cost Optimization strategies

See references/configuration.md

---

Anti-Patterns to Avoid

❌ Inventing model names or adding date suffixes: Why wrong: Image generation models have specific names; date suffixes like -preview-05-20 are for text models only Better: Use exactly gemini-2.5-flash-image or gemini-3-pro-image-preview — no variations

❌ Using Gemini 2.5 Pro for images: Why wrong: Gemini 2.5 Pro doesn't generate images directly Better: Use gemini-2.5-flash-image or gemini-3-pro-image-preview

❌ Storing only base64 in database: Why wrong: Blobs database, expensive storage, slow retrieval Better: Store in object storage (Vercel Blob/S3), save URL only

❌ No rate limit handling: Why wrong: Will hit 429 errors in production, poor UX Better: Implement rate limiting with user-friendly error messages

❌ Ignoring multi-turn context: Why wrong: Wastes Nano Banana's conversational editing strength Better: Track chat history for iterative refinement

❌ Hardcoding API keys client-side: Why wrong: Exposes credentials, security risk Better: Use server actions / API routes with environment variables

❌ Using wrong aspect ratio: Why wrong: 21:9 on 1:1 request wastes tokens, unexpected crop Better: Match aspect ratio to intended use case

❌ No loading states: Why wrong: Image generation takes 5-30s, users think it's broken Better: Show progress indicators and estimated wait time

❌ Generating on every keystroke: Why wrong: Wastes quota, slow response Better: Debounce prompts, require explicit action

---

Variation Guidance

IMPORTANT: Every app should feel uniquely designed for its specific purpose.

Vary across dimensions:

• UI Style: Minimal, brutalist, playful, professional, dark, light
• Color Scheme: Warm, cool, monochrome, vibrant, muted
• Layout: Single page, multi-step wizard, sidebar, grid, list
• Interaction: Click-to-generate, drag-and-drop, real-time typing, batch

Avoid overused patterns:

• ❌ Default Tailwind purple gradients
• ❌ Generic "AI startup" aesthetic
• ❌ Same component libraries for every project
• ❌ Inter/Roboto fonts without thought

Context should drive design:

• Meme generator → Bold, fun, casual
• Product mockup tool → Clean, professional, grid-based
• Art exploration → Gallery-first, visual-heavy
• Brand asset creator → Polished, template-guided

---

Environment Setup

# .env.local
GEMINI_API_KEY=your_api_key_here

# For Vercel Blob storage
BLOB_READ_WRITE_TOKEN=your_vercel_token

# For S3 (optional)
S3_BUCKET=your-bucket
S3_ENDPOINT=https://your-endpoint.r2.cloudflarestorage.com
S3_ACCESS_KEY_ID=your_key
S3_SECRET_ACCESS_KEY=your_secret

# For Upstash rate limiting (optional)
UPSTASH_REDIS_REST_URL=your_url
UPSTASH_REDIS_REST_TOKEN=your_token

# Install dependencies
npm install @ai-sdk/google ai @ai-sdk/react @vercel/blob

# Or if using separate packages
npm install google-genai

---

Remember

Nano Banana enables conversational image generation that feels like working with a creative partner, not a tool.

The best apps:

• Leverage multi-turn editing for refinement
• Choose models intentionally (speed vs quality)
• Handle rate limits gracefully
• Store images efficiently
• Provide great loading states
• Feel uniquely designed for their purpose

You're building more than an image generator—you're creating a creative experience. Design it thoughtfully.