I.R.I.S.

Intelligent Rendering & Image Synthesis – Local AI Image Generation

Search

Find answers quickly

Setup

Installation & configuration

FAQ

Frequently asked questions

Usage Guide

Features & parameters

Artifacts

Common issues & fixes

Prompt Engineering

Write better prompts

Troubleshooting

Fix common problems

API Reference

REST & WebSocket APIs

Screenshots

UI examples

Search Documentation

Find answers quickly across all documentation

Quick searches:

Start Searching

Type your question or topic in the search box above

Setup Guide

Complete Installation Guide for I.R.I.S.

Contents

System Requirements

TierGPUVRAMNotes
MinimumGTX 16504GBDRAM Extension recommended
Sweet SpotIntel Arc B58012GBBest value for money
AdvancedRTX 4070 Super12GBFast inference
ProfessionalRTX 409024GBNo-compromise
CPU Only8+ cores–16GB+ RAM, very slow

💡 I.R.I.S. was developed and tested on a GTX 1650, proving functionality on low-end hardware.

Installation

git clone https://github.com/KaiTooast/iris.git
cd iris

python -m venv venv
# Windows:
venv\Scripts\activate
# Linux/macOS:
source venv/bin/activate

pip install -r requirements.txt

# Optional: Copy environment template
cp .env.example .env

Configuration

settings.json

Main configuration file in project root:

{
  "dramEnabled": true,      // Use system RAM for low VRAM GPUs
  "vramThreshold": 6,       // VRAM threshold (GB) for DRAM Extension
  "maxDram": 8,             // Maximum system RAM to use (GB)
  "nsfwStrength": 2,        // 1=Minimal, 2=Standard, 3=Strict
  "discordEnabled": false   // Auto-start Discord bot
}

.env (Optional)

For Discord bot and advanced settings:

HOST=0.0.0.0
PORT=8000
DISCORD_BOT_TOKEN=your_token
DISCORD_CHANNEL_NEW_IMAGES=channel_id
DISCORD_CHANNEL_VARIATIONS=channel_id
DISCORD_CHANNEL_UPSCALED=channel_id

First Run

# Auto-start based on settings.json
python src/start.py

# Force start without Discord bot
python src/start.py --no-bot

On first run, the AI model will download (~5GB). This only happens once per model.

🌐 Open: http://localhost:8000

Usage Guide

Master I.R.I.S. with this comprehensive guide

Basic Usage

1. Launch

python src/start.py

Open http://localhost:8000 → Click "Generate"

2. Write Your Prompt

Describe what you want to see:

"a detailed portrait of a cyberpunk warrior, neon lighting, highly detailed, masterpiece, 8k"

3. Adjust Parameters

  • Steps: 20-35 for most images (default: 35)
  • CFG Scale: 8-12 for balanced results (default: 10)
  • Resolution: 512×768 recommended for low VRAM

Parameters Explained

CFG Scale (Guidance)

Controls how closely the AI follows your prompt.

  • Low (5-7): More creative, less accurate
  • Medium (8-12): Balanced (recommended)
  • High (15+): Very literal, may oversaturate

Sampling Steps

  • 20 steps: Fast, decent quality
  • 30-35 steps: Good balance (default)
  • 50+ steps: Diminishing returns

Seed

Use -1 for random. Same seed + same prompt = same image. Great for variations.

Upscaling

Select an image from the library and click "Upscale" to enhance resolution.

Lanczos

Fast, always available. Good for quick upscales.

Real-ESRGAN

AI-powered, better quality. Requires additional setup.

Scale factors: 2×, 4× (8× available via API)

Generation Queue

Queue multiple generations and process them sequentially.

  • Add items to queue via API or batch endpoint
  • Reorder, cancel, or remove pending items
  • Process all at once or one by one
  • View queue statistics and history

Discord Bot

Optional Discord integration for automatic image posting.

  1. Create a bot at Discord Developer Portal
  2. Copy the Bot Token to .env
  3. Set channel IDs for new images, variations, and upscaled images
  4. Enable in settings.json: "discordEnabled": true

The bot automatically posts generated images to configured channels.

Prompt Engineering

Master the art of writing effective prompts

Prompt Structure

Basic Template:
[Subject] + [Style] + [Quality] + [Details]

1. Subject (What)

The main focus: "a warrior", "mountain landscape", "futuristic city"

2. Style (How it looks)

Art style: "digital art", "oil painting", "photorealistic", "anime"

3. Quality Tags

Modifiers: "masterpiece", "highly detailed", "8k", "professional"

Effective Examples

Portrait

"close-up portrait of a woman, studio lighting, bokeh background, professional photography, highly detailed, 8k"

Cyberpunk

"cyberpunk city street at night, neon lights, rain puddles reflecting lights, blade runner style, cinematic"

Pixel Art

"pixel art forest scene, 16-bit style, retro game aesthetic, vibrant colors"

Use the "pixel_art" style for automatic pixel art prompting.

Negative Prompts

Tell the AI what you DON'T want. Essential for quality results.

Common Negative Prompt:
"low quality, worst quality, blurry, distorted, ugly, deformed, bad anatomy, extra limbs, watermark, text"

I.R.I.S. automatically adds "lowres, bad anatomy, worst quality" if no negative prompt is provided.

Artifact Gallery

When AI gets a little too creative. Common artifacts & how to fix them.

What Are Artifacts?

Visual errors caused by conflicting data, resolution limits, or prompt ambiguity.

The Clone Saga

Symptom: Two (or more) heads, merged faces

Cause: High resolution (1024px+) without proper training

Fix: Use 512×768 and upscale afterwards

Hand Horror

Symptom: 6+ fingers, backwards thumbs

Cause: Confusing hand pose training data

Fix: Add normal hands, five fingers to prompt

Almost-Words

Symptom: Text like "ČÅFĒ" instead of "CAFE"

Cause: Stable Diffusion is bad at text

Fix: Add text in post-processing or use SDXL models

Prevention Tips

  1. Start small: 512×512 → upscale
  2. Use strong negative prompts
  3. Simple prompts beat complex ones
  4. Test different seeds
  5. CFG sweet spot: 8–12 (not 20)

FAQ

Frequently Asked Questions

Troubleshooting

Solutions to common problems

Quick Fixes

Out of Memory

  • Reduce resolution to 512×512
  • Enable DRAM Extension
  • Reduce steps to 20-30
  • Close other applications

CUDA Not Detected

  • Update NVIDIA drivers
  • Reinstall PyTorch + CUDA
  • Verify GPU in Device Manager
  • Check CUDA installation

Slow Generation

  • Check if CUDA is being used
  • Update GPU drivers
  • Close background processes
  • Reduce resolution/steps

Poor Image Quality

  • Adjust CFG scale (8-12)
  • Increase steps to 30-35
  • Improve prompt quality
  • Add negative prompts

Discord Bot Not Working

  • Verify Bot Token is correct
  • Check Channel IDs are valid
  • Ensure bot has permissions
  • Check discordEnabled in settings

Model Download Stuck

  • Check internet connection
  • Try again (downloads resume)
  • Clear ~/.cache/huggingface
  • Use VPN if region-blocked

Useful Commands

Check CUDA availability:

python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

Check GPU info:

python -c "import torch; print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'No GPU')"

Reinstall PyTorch with CUDA 11.8:

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

API Reference

REST API & WebSocket Integration

Getting Started

Base URL

http://localhost:8000

All endpoints are available without authentication for local use.

REST Endpoints

POST /api/generate

Generate an image from a text prompt.

{
  "prompt": "a detailed portrait, highly detailed",
  "negative_prompt": "low quality, blurry",
  "steps": 35,
  "cfg_scale": 10.0,
  "width": 512,
  "height": 768,
  "seed": -1,
  "style": "anime_kawai"
}
POST /api/upscale

Upscale an existing image.

{
  "filename": "gen_20260112_123456_789.png",
  "scale": 2,
  "method": "lanczos"  // or "realesrgan"
}
GET /api/output-gallery

Get list of all generated images.

GET /api/settings

Get current application settings.

POST /api/settings

Update application settings (dramEnabled, nsfwStrength, etc.).

GET /api/vram-status

Get current VRAM usage and availability.

GET /api/queue

Get all queue items and statistics.

POST /api/queue/add

Add an item to the generation queue.

WebSocket

Generation with Progress

ws://localhost:8000/ws/generate

Real-time progress updates during image generation.

Gallery Updates

ws://localhost:8000/ws/gallery-progress

Live updates when new images are generated.

Python Example

import requests

url = "http://localhost:8000/api/generate"
data = {
    "prompt": "a beautiful sunset over mountains, masterpiece",
    "negative_prompt": "low quality, blurry",
    "steps": 30,
    "cfg_scale": 10,
    "width": 512,
    "height": 768
}

response = requests.post(url, json=data)
result = response.json()

if result["success"]:
    print(f"Generated: {result['filename']}")
    print(f"Seed: {result['seed']}")
    print(f"Time: {result['generation_time']}s")