API for fetching random chinchilla images from Wikimedia Commons and Pixabay. Built with Next.js 15 and TypeScript, hosted on Vercel, images stored in Cloudinary.

✨ Features

• 🎲 Random domestic chinchilla images
• 📝 Metadata with author information and source links
• ⚡ Serverless API on Next.js
• 🖼️ Optimized WebP images via Cloudinary
• 📚 Interactive API documentation
• 🌐 Deployed on Vercel

🚀 Quick Start

Local Development

1. Install dependencies:

npm install

2. Create .env.local file:

cp .env.local.example .env.local

3. Fill in environment variables in .env.local:

Register at cloudinary.com and get your credentials:

CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

4. Start dev server:

npm run dev

Open http://localhost:3000 in your browser.

Uploading Images to Cloudinary

After setting up Cloudinary credentials:

npm run upload

This script will:

• Upload all WebP images from images-webp/ to Cloudinary
• Update public/metadata.json with Cloudinary URLs
• Create checkpoints every 5 uploads

📡 API Endpoints

GET /api/random

Returns a random chinchilla image with metadata.

Response:

{
  "image": "https://res.cloudinary.com/.../chinchilla.webp",
  "author": "Wikipedia User",
  "mediawikiUrl": "https://commons.wikimedia.org/wiki/File:...",
  "pixabayUrl": "https://pixabay.com/photos/...",
  "basename": "Chinchilla_1",
  "source": "wikimedia"
}

GET /api/random/info

Returns metadata only (without the image data).

Response:

{
  "basename": "Chinchilla_1",
  "author": "Wikipedia User",
  "mediawikiUrl": "https://commons.wikimedia.org/wiki/File:...",
  "pixabayUrl": "https://pixabay.com/photos/...",
  "webpFile": "File_Chinchilla_1_by_User.webp",
  "cloudinaryUrl": "https://res.cloudinary.com/...",
  "source": "wikimedia"
}

🛠️ Tech Stack

• Framework: Next.js 15 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS
• Image Storage: Cloudinary
• Hosting: Vercel
• Image Sources: Wikimedia Commons, Pixabay

📁 Project Structure

random-chinchilla-api/
├── app/
│   ├── api/
│   │   └── random/           # API endpoints
│   ├── layout.tsx            # Root layout
│   ├── page.tsx              # Main page
│   └── globals.css           # Global styles
├── lib/
│   ├── cloudinary.ts         # Cloudinary utilities
│   └── metadata.ts           # Metadata loader
├── types/
│   └── chinchilla.ts         # TypeScript types
├── scripts/
│   ├── index.js              # Wiki parser (original)
│   ├── convert-to-webp.js    # WebP converter (original)
│   ├── upload-to-cloudinary.ts # Cloudinary uploader
│   ├── parse-pixabay.js      # Pixabay parser
│   └── process-pixabay.ts    # Pixabay processor
├── public/
│   └── metadata.json         # Image metadata
└── images-webp/              # Local WebP images

🚢 Deploy to Vercel

1. Create Git repository:

git init
git add .
git commit -m "Initial commit"

2. Push to GitHub:

   git remote add origin https://github.com/yourusername/random-chinchilla-api.git
   git push -u origin main

3. Connect to Vercel:

• Go to vercel.com
• Import your GitHub repository
• Vercel will automatically detect Next.js project

4. Configure Environment Variables in Vercel:

In project settings, add:

• CLOUDINARY_CLOUD_NAME
• CLOUDINARY_API_KEY
• CLOUDINARY_API_SECRET

5. Deploy:

Vercel will automatically deploy your project!

🔧 Scripts

• npm run dev - Start dev server
• npm run build - Build for production
• npm start - Start production server
• npm run upload - Upload images to Cloudinary
• npm run parse-pixabay - Parse images from Pixabay
• npm run process-pixabay - Convert and upload Pixabay images

📝 Original Scripts

The scripts/ directory contains original scripts:

• index.js - Wikimedia Commons parser for downloading images
• convert-to-webp.js - Image converter to WebP format
• parse-pixabay.js - Pixabay API parser

Use them to expand the image collection.

📊 Statistics

Current collection: ~100+ images of domestic chinchillas from Wikimedia Commons and Pixabay.

📄 License

Images from Wikimedia Commons are distributed under various free licenses. Each image contains a link to the original with license and author information.

Images from Pixabay are available under the Pixabay License.

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests.

📋 TODO

• Add changelog
• Set up pre-commit hooks
• Add development guidelines and instructions

---

Made with ❤️ by Pavel Kuzyakin using Next.js and Cloudinary