From c8060de5c236e632b07647a37868890179d20e91 Mon Sep 17 00:00:00 2001 From: Anil Matcha Date: Fri, 13 Feb 2026 15:27:20 +0530 Subject: [PATCH] docs: Update README with project features, architecture and setup instructions --- README.md | 144 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 86 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 325a91d..4961fda 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 + +```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. + +### Production Build + +```bash +npm run build +npm run preview +``` + +## 🏗️ Architecture + +``` +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 +``` + +## 🔌 API Integration + +The app communicates with [Muapi.ai](https://muapi.ai) using a two-step pattern: + +1. **Submit** — `POST /api/v1/{model-endpoint}` with prompt and parameters +2. **Poll** — `GET /api/v1/predictions/{request_id}/result` until status is `completed` + +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 -* **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). +- **Vite** — Build tool & dev server +- **Tailwind CSS v4** — Utility-first styling +- **Vanilla JS** — No framework, pure DOM manipulation +- **Muapi.ai** — AI model API gateway -## 📦 Installation +## 📄 License -1. Clone the repository: - ```bash - git clone https://github.com/yourusername/open-higgsfield-ai.git - cd open-higgsfield-ai - ``` +MIT -2. Install dependencies: - ```bash - npm install - ``` +## 🙏 Credits -3. Run the development server: - ```bash - npm run dev - ``` - -4. Open `http://localhost:5173` in your browser. - -## 🔑 Configuration - -To use the generation features, you need a Muapi API Key. - -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. - -## 🛣️ Roadmap - -- [ ] **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 - ---- - -*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.