docs: Update README with project features, architecture and setup instructions
This commit is contained in:
Anil Matcha
parent
e0efb745d5
commit
c8060de5c2
1 changed files with 86 additions and 58 deletions
144
README.md
144
README.md
|
|
@ -1,72 +1,100 @@
|
|||
# Open-Higgsfield AI 🎥✨
|
||||
# Open Higgsfield AI
|
||||
|
||||
|
||||
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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue