| Landing | Map Editor | Collection |
|---|---|---|
 |
 |
 |
- Pan & explore — move the map anywhere in the world; location is detected automatically via reverse geocoding
- 3 AI models — choose between Nano Banana, Nano Banana 2, and Nano Banana Pro based on speed and quality needs (see Models)
- 6 art styles — Watercolor, Vintage, Ink Sketch, Oil Paint, Ancient Ink, Cyberpunk
- 7 aspect ratios — 1:1, 4:3, 3:4, 16:9, 9:16, 3:2, 2:3
- Postcard back — a matching decorative back side is generated alongside the front
- Upload a photo — add yourself into the scene; the AI redraws you in the postcard's artistic style
- Collection binder — generated postcards are collected in a floating ring-binder panel; session-only (cleared on page refresh)
- Lucky spin — the compass button picks a random city and style for instant inspiration
- Cost estimate — token usage and estimated USD cost displayed after each generation
| Name | Model ID | Speed | Quality | Free tier |
|---|---|---|---|---|
| Nano Banana | gemini-2.5-flash-image |
Fast | Good | Yes |
| Nano Banana 2 | gemini-3.1-flash-image-preview |
Fast | Better | Yes |
| Nano Banana Pro | gemini-3-pro-image-preview |
Slow | Best | No — paid API key required |
Cost is estimated from token counts × Google AI published rates. Actual billing may differ.
 |
 |
 |
| Watercolor · Barcelona | Oil Paint · London | Ancient Ink · Guilin |
 |
 |
 |
| Vintage · Tokyo | Sketch · Chengdu | Cyberpunk · Singapore |
Prerequisites: Node.js 18+
git clone https://github.com/Aryous/PostcardMapAI.git
cd PostcardMapAI
npm install
npm run devOpen http://localhost:3000.
API Key: Get one free at aistudio.google.com/apikey. You can enter it directly in the app (bottom-left key icon) — no config files needed.
Alternatively, create a .env.local file:
GEMINI_API_KEY=your_key_here
After deploying, add the environment variable in Settings → Environment Variables:
| Name | Value |
|---|---|
GEMINI_API_KEY |
Your Gemini API key (optional — users can also enter their own) |
npm i -g vercel
vercel login
vercel --prod- Push this repo to your GitHub account
- Import it at vercel.com/new
- Optionally add
GEMINI_API_KEYas an environment variable - Every push to
mainauto-deploys
- React + TypeScript + Vite
- Leaflet — interactive map
- Google Gemini API — multi-model image generation with Nano Banana (
gemini-2.5-flash-image), Nano Banana 2 (gemini-3.1-flash-image-preview), and Nano Banana Pro (gemini-3-pro-image-preview) - html2canvas — map screenshot
- Nominatim — reverse geocoding (OpenStreetMap)
- Tailwind CSS (CDN)
- History is session-only — generated postcards are lost on page refresh; there is no persistent storage
- Nano Banana Pro requires a paid API key — free-tier keys return a 403 error for
gemini-3-pro-image-preview - Map tile CORS — screenshots depend on tile providers allowing CORS; some custom tile layers may render blank
- Cost estimates are approximate — calculated from token counts, not actual billing data from Google