0ef7e5475c
- Add Python FastAPI backend with Pydantic validation - Port WhiskClient and MetaAIClient to Python - Create API routers for all endpoints - Add Swagger/ReDoc documentation at /docs - Update Dockerfile for multi-service container - Add lib/api.ts frontend client - Update README for V3
127 lines
4.3 KiB
Markdown
127 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
cd backend
|
|
source venv/bin/activate
|
|
uvicorn main:app --reload --port 8000
|
|
```
|
|
|
|
**Terminal 2 - Frontend:**
|
|
```bash
|
|
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)
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
### Using Docker CLI
|
|
```bash
|
|
# 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](https://nextjs.org/) (App Router) + [Tailwind CSS](https://tailwindcss.com/)
|
|
- **Backend**: [FastAPI](https://fastapi.tiangolo.com/) + [Pydantic](https://docs.pydantic.dev/)
|
|
- **State**: [Zustand](https://github.com/pmndrs/zustand)
|
|
- **Icons**: [Lucide React](https://lucide.dev/)
|
|
|
|
### 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](https://labs.google/fx/tools/image-fx)
|
|
- Grok: [grok.com](https://grok.com)
|
|
- Meta: [meta.ai](https://www.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
|