Web UI for Stable Diffusion REST API

A modern, responsive web interface has been implemented for the Stable Diffusion REST API server.

Integrated Mode (Recommended)

The web UI is now integrated into the REST server and served at /ui. The web UI is automatically built when you build the server!

1. Build the server (automatically builds web UI):

mkdir build && cd build
cmake ..
cmake --build .

The web UI will be automatically built and placed in build/webui/.

Note: Node.js and npm must be installed for the web UI to build. If npm is not found, the build will continue without the web UI.

2. Start the server with UI enabled:

./src/stable-diffusion-rest-server \
  --models-dir /path/to/models \
  --checkpoints checkpoints \
  --ui-dir ../webui

Note: You must explicitly specify --ui-dir to enable the web UI. The path should point to the built static files in build/webui/.

Dynamic Configuration: The web UI automatically detects the server's host and port at runtime! No need to rebuild the UI when changing ports - just start the server on any port and the UI will work automatically.

3. Open your browser:

Navigate to http://localhost:8080/ui/

The web UI will be served directly by the REST server at the /ui path!

Running on Custom Ports

The web UI automatically adapts to any port you specify:

# Run on port 3000
./src/stable-diffusion-rest-server \
  --models-dir /path/to/models \
  --checkpoints checkpoints \
  --ui-dir ../webui \
  --port 3000

# Access at http://localhost:3000/ui/

No rebuild required! The UI automatically detects the server configuration at runtime.

CMake Options

You can control the web UI build with CMake options:

# Disable web UI building
cmake .. -DBUILD_WEBUI=OFF

# Enable web UI building (default)
cmake .. -DBUILD_WEBUI=ON

Manual UI Directory

If you want to specify a custom UI directory:

./src/stable-diffusion-rest-server \
  --models-dir /path/to/models \
  --checkpoints checkpoints \
  --ui-dir /path/to/custom/ui

Standalone Mode (Development)

For development or if you prefer to run the web UI separately:

1. Navigate to the Web UI directory:

cd webui

2. Install dependencies:

npm install

3. Configure the API endpoint (for development only):

For standalone development mode, you need to configure the API endpoint.

Edit .env.local and uncomment:

NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_API_BASE_PATH=/api

Note: This is only needed when running npm run dev. In production (integrated mode), the server automatically injects the configuration.

4. Start the development server:

npm run dev

5. Open your browser:

Navigate to http://localhost:3000

Features

The web UI includes the following features:

🎨 Text-to-Image Generation

Full parameter control (prompt, negative prompt, dimensions, steps, CFG scale)
Multiple sampling methods (Euler, Euler A, Heun, DPM++, LCM, etc.)
Batch generation support
Real-time job tracking
Download generated images

🖼️ Image-to-Image

Upload source images
Adjustable transformation strength
Full parameter control
Image preview and download

✨ Upscaler

2x, 3x, 4x upscaling options
ESRGAN and RealESRGAN model support
Image upload and download

⚙️ Model Management

View all available models (checkpoints, LoRA, VAE, etc.)
Load/unload models
Filter models by type
Search functionality
Scan for new models
Real-time model status

📊 Queue Monitor

Real-time job tracking
Auto-refresh capability
Job progress visualization
Cancel jobs
Clear queue
View generated images
Job history

🎨 Theme Support

Automatic dark/light mode based on system preference
Manual theme toggle
Modern, clean design
Fully responsive layout

Production Deployment

Build for production:

npm run build

Start production server:

npm start

The production server will run on port 3000 by default.

Using a different port:

PORT=3001 npm start

Project Structure

webui/
├── app/                    # Next.js 15 App Router pages
│   ├── text2img/          # Text-to-image generation
│   ├── img2img/           # Image-to-image transformation
│   ├── upscaler/          # Image upscaling
│   ├── models/            # Model management
│   ├── queue/             # Queue monitoring
│   └── page.tsx           # Home page
├── components/            # React components
│   ├── ui/                # Reusable UI components
│   ├── sidebar.tsx        # Navigation
│   ├── header.tsx         # Page headers
│   ├── theme-toggle.tsx   # Theme switcher
│   └── ...
├── lib/                   # Utilities
│   ├── api.ts             # API client
│   └── utils.ts           # Helper functions
└── public/                # Static assets

Technology Stack

Framework: Next.js 15 with App Router
Language: TypeScript
Styling: Tailwind CSS v4
State Management: React Hooks
Icons: Lucide React
Theme: next-themes

API Requirements

The web UI expects the following API endpoints to be available:

GET /api/v1/health - Health check
GET /api/v1/models - List models
POST /api/v1/text2img - Generate from text
POST /api/v1/img2img - Transform images
GET /api/v1/queue - Queue status
GET /api/v1/jobs/{id} - Job status
POST /api/v1/models/load - Load model
And more...

Make sure your REST API server is running and accessible before using the web UI.

Development

For detailed development information, see webui/README.md.

Troubleshooting

Cannot connect to API

Ensure the REST API server is running
Check the API URL in .env.local
Verify CORS is properly configured on the backend

Build errors

Delete .next folder and node_modules
Run npm install again
Ensure Node.js version is 18 or higher

For more information, see the full documentation in the webui directory.

Technical Details

Dynamic Configuration System

The web UI uses a dynamic configuration system that eliminates the need to rebuild when changing ports or hosts:

Server-Side Injection: When you start the server with --ui-dir, it automatically serves a /ui/config.js endpoint
Runtime Configuration: This JavaScript file contains the current server host and port
Automatic Detection: The web UI loads this config on startup and uses it for all API calls

Benefits:

✅ No need to rebuild the UI when changing ports
✅ No .env configuration required in production
✅ Works with any host/port combination
✅ Single build works everywhere

Example config.js generated by server:

window.__SERVER_CONFIG__ = {
  apiUrl: 'http://localhost:8080',
  apiBasePath: '/api',
  host: 'localhost',
  port: 8080
};

This configuration is automatically loaded before the UI initializes, ensuring all API requests go to the correct server endpoint.

WEBUI.md 7.1 KB Histórico Raw