Picurio

Bo samo zdjęcie to za mało.

Live demo

Picurio is a Polish-language web application that turns a photo or location into a social media caption, an interesting fact, and a set of relevant hashtags. The full version combines image recognition, optional GPS metadata, and AI-generated content in one responsive Next.js application.

The repository also includes a safe demo mode designed for a public portfolio deployment. Demo mode uses curated local responses and never calls external AI services.

Features

• AI-generated captions, facts, and hashtags in the full application
• Image recognition with optional GPS/EXIF context
• Client-side HEIC/HEIF conversion
• Informative, funny, and poetic caption styles
• Polish-language interface and generated content
• Responsive, mobile-first UI
• One-click copy actions
• Cost-free demo mode for public deployments

Demo mode

Set the following public environment variable:

NEXT_PUBLIC_DEMO_MODE=true

When demo mode is enabled:

• OpenAI and Gemini clients are not initialized;
• no API keys are required;
• uploaded photos stay in the browser and are used only for local preview;
• image recognition is transparently simulated with a predefined example;
• caption generation uses curated responses for the provided example locations;
• arbitrary locations receive an explicit demo fallback instead of an invented fact.

The available curated examples are:

• Wieża Eiffla, Paryż
• Koloseum, Rzym
• Pałac Kultury i Nauki, Warszawa
• Machu Picchu, Peru

This mode is intended for a public portfolio website. It demonstrates the complete product flow without exposing secrets or creating external API costs.

Tech stack

• Next.js 16 with App Router
• React 19 and TypeScript
• Tailwind CSS and shadcn/ui components
• Next.js Route Handlers
• OpenAI API for content generation in full mode
• Google Generative AI for image recognition in full mode
• pnpm

Getting started

Requirements

• Node.js 20.9 or newer
• pnpm 10

Installation

git clone https://github.com/KaszubDev/picurio.git
cd Picurio
pnpm install
cp .env.example .env

For the safe demo configuration, keep:

NEXT_PUBLIC_DEMO_MODE=true

Then start the development server:

pnpm dev

Open http://localhost:3000.

Full AI mode

To run the complete application locally, use:

NEXT_PUBLIC_DEMO_MODE=false
OPENAI_API_KEY=your-openai-api-key
GEMINI_API_KEY=your-gemini-api-key

# Optional model override for the image recognition route
GEMINI_MODEL_NAME=your-supported-gemini-model

In full mode:

• /api/generate calls the OpenAI model configured in its route;
• /api/recognize calls the Gemini model configured in its route or overridden by GEMINI_MODEL_NAME.

Never commit a real .env file. The repository tracks only .env.example containing empty placeholders.

Available scripts

pnpm dev
pnpm run lint
pnpm run build
pnpm start

API routes

Route	Method	Purpose
/api/generate	POST	Returns { caption, fact, hashtags }
/api/recognize	POST	Returns { location }

The endpoints remain available in demo mode, but they return local, deterministic demo data and do not communicate with external AI providers.

Project structure

src/
├── app/
│   ├── api/
│   │   ├── generate/
│   │   └── recognize/
│   ├── layout.tsx
│   └── page.tsx
├── components/
├── lib/
│   ├── api.ts
│   ├── demo.ts
│   └── utils.ts
├── styles/
├── config.ts
└── types.ts

Privacy and cost safety

The public demo requires no provider credentials. Because external AI calls are disabled at the server level, calling the public API endpoints cannot consume the owner's OpenAI or Gemini quota. Uploaded images are not transmitted to the server in demo mode.

Full mode should not be exposed publicly without additional abuse protection such as per-user quotas, rate limiting, bot protection, and provider spending limits.

License

MIT

Author

Krzysztof Kaszubowski — @KaszubDev