kv-pix (V3)

A modern, full-stack AI Image Generator with FastAPI backend and Next.js frontend. Powered by Google ImageFX (Whisk), Grok, and Meta AI.

🆕 What's New in V3

• FastAPI Backend - Python backend with automatic Swagger documentation
• Better Security - Centralized CORS, Pydantic validation, structured error handling
• API Documentation - Interactive docs at /api/docs (Swagger) and /api/redoc
• Improved Architecture - Clean separation of frontend and backend

🚀 Quick Start

Prerequisites

• Node.js 18+
• Python 3.11+
• Whisk/Grok/Meta Cookies (from respective services)

Installation

# Install frontend dependencies
npm install

# Set up backend
cd backend
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Run Locally

Terminal 1 - Backend:

cd backend
source venv/bin/activate
uvicorn main:app --reload --port 8000

Terminal 2 - Frontend:

npm run dev

Service	URL
Frontend	http://localhost:3000
Backend API	http://localhost:8000
Swagger UI	http://localhost:8000/docs
ReDoc	http://localhost:8000/redoc

🐳 Docker Deployment (Synology NAS / linux/amd64)

Using Docker Compose (Recommended)

docker-compose up -d

Using Docker CLI

# Pull from registry
docker pull git.khoavo.myds.me/vndangkhoa/apix:v3

# Run
docker run -d -p 3000:3000 -p 8000:8000 --name kv-pix git.khoavo.myds.me/vndangkhoa/apix:v3

🏗️ Architecture

┌─────────────────┐     HTTP/REST      ┌──────────────────┐
│   Next.js UI    │ ◄───────────────► │   FastAPI Backend │
│   (Port 3000)   │                    │   (Port 8000)     │
└─────────────────┘                    └────────┬─────────┘
                                                │
                                    ┌───────────┴───────────┐
                                    │                       │
                              ┌─────▼─────┐          ┌──────▼──────┐
                              │ WhiskAPI  │          │  MetaAI API │
                              └───────────┘          └─────────────┘

Tech Stack

• Frontend: Next.js 15 (App Router) + Tailwind CSS
• Backend: FastAPI + Pydantic
• State: Zustand
• Icons: Lucide React

Project Structure

├── app/            # Next.js pages and (legacy) API routes
├── backend/        # FastAPI Python backend
│   ├── main.py
│   ├── routers/    # API endpoints
│   ├── services/   # Business logic (whisk_client, meta_client)
│   └── models/     # Pydantic request/response models
├── components/     # React UI components
├── lib/            # Frontend utilities and API client
├── data/           # Prompt library JSON
└── public/         # Static assets

✨ Features

• Multi-Provider: Google Whisk (ImageFX), Grok (xAI), Meta AI (Imagine)
• FastAPI Backend: Type-safe Python API with auto-documentation
• Prompt Library: Curated prompts organized by categories
• Upload History: Reuse previously uploaded reference images
• Reference Chips: Drag-and-drop references for Subject/Scene/Style
• Video Generation: Animate images with Whisk Animate (Veo)
• Responsive Gallery: Masonry layout with smooth animations
• Dark Mode: Material 3 inspired aesthetic

🍪 Cookie Configuration

1. Go to the respective service:
   • Whisk: ImageFX
   • Grok: grok.com
   • Meta: meta.ai
2. Open DevTools (F12) → Application → Cookies.
3. Copy the cookie string (or use a "Get Cookies" extension to copy as JSON).
4. Paste into the Settings menu in the app.

📝 License

MIT