Skip to content

Unrestricted Open-source alternative to AI video platforms — Free AI image & video generation studio with 600+ models (Flux, Midjourney, Kling, Sora, Veo). No content filters. Self-hosted, MIT licensed.

docs: Update README with project features, architecture and setup instructions

Anil Matchac8060de5c236
diff --git a/README.md b/README.md
index 325a91d8..4961fdaa 100644
--- a/README.md
+++ b/README.md
@@ -1,72 +1,100 @@
-# Open-Higgsfield AI 🎥✨
+# Open Higgsfield AI
-![Open-Higgsfield Banner](public/banner.png)
+An open-source AI image generation studio powered by [Muapi.ai](https://muapi.ai). Generate stunning images using state-of-the-art models like Flux Schnell, Flux Dev, Nano Banana Pro, and more — all from a sleek, modern interface.
-A local, open-source clone of **Higgsfield AI**, powered by [Muapi](https://muapi.ai) for high-end video and image generation. This project aims to replicate the premium experience of Higgsfield's studios locally, giving you control over your creative workflow with your own API keys.
+## ✨ Features
-## 🚀 Features
+- **Multi-Model Support** — Switch between 20+ AI image generation models (Flux, Nano Banana, Ideogram, Midjourney, SDXL, and more)
+- **Smart Controls** — Dynamic aspect ratio and resolution pickers that adapt to each model's capabilities
+- **Generation History** — Browse, revisit, and download all your past generations (persisted in browser storage)
+- **Image Download** — One-click download of generated images in full resolution
+- **API Key Management** — Secure API key storage in browser localStorage (never sent to any server except Muapi)
+- **Responsive Design** — Works seamlessly on desktop and mobile with dark glassmorphism UI
-### 1. AI Image Studio 🎨
-* **High-Fidelity Generation**: Create stunning visuals using top-tier models like **Flux.1 Dev** and **SDXL**.
-* **Advanced Controls**: Fine-tune your output with negative prompts, aspect ratio selection (1:1, 16:9, 9:16), and seed control.
-* **Gallery**: Persistent history of your generations.
+## 🚀 Quick Start
-### 2. AI Video Studio 🎬
-* **Text-to-Video (T2V)**: Turn your scripts into cinematic videos using models like **Wan 2.5** and **Google Veo**.
-* **Image-to-Video (I2V)**: Bring static images to life with motion.
-* **Motion Buckets**: Control the intensity of movement (Static, Gentle, Dynamic).
+### Prerequisites
-### 3. Cinema Studio 🎥
-* **Pro Camera Controls**: Simulate real manufacturing lenses (e.g., *Studio Digital S35*).
-* **Physical Movements**: Control Zoom, Pan, Tilt, and Roll just like a real camera.
-* **Directors Mode**: Precise keyframing for camera trajectories (Coming Soon).
+- [Node.js](https://nodejs.org/) (v18+)
+- A [Muapi.ai](https://muapi.ai) API key
-### 4. Soul ID & Lipsync 🗣️
-* **Character Consistency**: Maintain character identity across multiple generations.
-* **Lipsync Studio**: Upload an audio file or type text to make your characters speak with perfect lip synchronization.
+### Setup
-## 🛠️ Tech Stack
+```bash
+# Clone the repository
+git clone https://github.com/Anil-matcha/Open-Higgsfield-AI.git
+cd Open-Higgsfield-AI
+
+# Install dependencies
+npm install
+
+# Start the development server
+npm run dev
+```
+
+Open `http://localhost:5173` in your browser. You'll be prompted to enter your Muapi API key on first use.
-* **Frontend**: [Vite](https://vitejs.dev/) + Vanilla JavaScript for lightning-fast performance.
-* **Styling**: Vanilla CSS (Custom Glassmorphism & Neon Design System).
-* **API Integration**: [Muapi.ai](https://muapi.ai) (Vadoo Engine).
-* **No Backend**: Runs entirely in the browser (Client-side API calls).
+### Production Build
-## 📦 Installation
+```bash
+npm run build
+npm run preview
+```
-1. Clone the repository:
- ```bash
- git clone https://github.com/yourusername/open-higgsfield-ai.git
- cd open-higgsfield-ai
- ```
+## 🏗️ Architecture
-2. Install dependencies:
- ```bash
- npm install
- ```
+```
+src/
+├── components/
+│ ├── ImageStudio.js # Main studio with prompt, pickers, canvas, history
+│ ├── Header.js # App header with settings and controls
+│ ├── AuthModal.js # API key input modal
+│ ├── SettingsModal.js # Settings panel for API key management
+│ └── Sidebar.js # Navigation sidebar
+├── lib/
+│ ├── muapi.js # API client (submit + poll pattern, x-api-key auth)
+│ └── models.js # Model definitions with endpoint mappings
+├── styles/
+│ ├── global.css # Global styles and animations
+│ ├── studio.css # Studio-specific styles
+│ └── variables.css # CSS custom properties
+├── main.js # App entry point
+└── style.css # Tailwind imports
+```
-3. Run the development server:
- ```bash
- npm run dev
- ```
+## 🔌 API Integration
-4. Open `http://localhost:5173` in your browser.
+The app communicates with [Muapi.ai](https://muapi.ai) using a two-step pattern:
-## 🔑 Configuration
+1. **Submit** — `POST /api/v1/{model-endpoint}` with prompt and parameters
+2. **Poll** — `GET /api/v1/predictions/{request_id}/result` until status is `completed`
-To use the generation features, you need a Muapi API Key.
+Authentication uses the `x-api-key` header. During development, a Vite proxy handles CORS by routing `/api` requests to `https://api.muapi.ai`.
+
+## 🎨 Supported Models
+
+| Model | Endpoint | Resolution Options |
+|-------|----------|-------------------|
+| Nano Banana | `nano-banana` | — |
+| Nano Banana Pro | `nano-banana-pro` | 1K, 2K, 4K |
+| Flux Schnell | `flux-schnell-image` | — |
+| Flux Dev | `flux-dev-image` | — |
+| Flux Dev LoRA | `flux-dev-lora` | — |
+| Ideogram V2 | `ideogram-v2` | — |
+| SDXL | `sdxl` | — |
+| And 15+ more... | | |
+
+## 🛠️ Tech Stack
-1. Go to [Muapi.ai Dashboard](https://muapi.ai/dashboard) and generate a key.
-2. Open the app settings (Gear icon).
-3. Paste your API Key. It defaults to browser `localStorage` for security.
+- **Vite** — Build tool & dev server
+- **Tailwind CSS v4** — Utility-first styling
+- **Vanilla JS** — No framework, pure DOM manipulation
+- **Muapi.ai** — AI model API gateway
-## 🛣️ Roadmap
+## 📄 License
-- [ ] **Phase 1**: AI Image Studio (Flux Integration)
-- [ ] **Phase 2**: AI Video Studio (Wan/Veo Integration)
-- [ ] **Phase 3**: Cinema Studio (Camera Motion Controls)
-- [ ] **Phase 4**: Soul ID & Lipsync Implementation
+MIT
----
+## 🙏 Credits
-*Disclaimer: This is a community project and is not affiliated with Higgsfield AI. Usage costs are dependent on your Muapi API usage.*
+Built with [Muapi.ai](https://muapi.ai) — the unified API for AI image generation models.