Discord AI Image Generator Bot

Production-ready Discord bot for AI image generation powered by SeedDream 5.0 Lite / 4.5 / 4.0 models, with MSSQL database, Redis queue system, role-based limits, rank management, and guild authorization system.

✨ Features

• Latest Models — Seedream 5.0 Lite (default), 4.5, and 4.0 support
• Sequential Generation — Generate multiple images in one API call (up to 15 images)
• Output Formats — PNG or JPEG with configurable quality
• Optimization Modes — Standard (better quality) or Fast (faster speed)
• Progress Tracking — Real-time download progress indicator (1/4, 2/4, etc.)
• K-Format Sizes — Support for 1K, 2K, 3K, 4K resolution presets
• Slash Commands — /generate, /img2img, /batchimg, /img2img-blending
• Guild Whitelist — Only authorized guilds can use the bot (database-managed)
• Role-Based Limits — Admin (unlimited), Paid User (100-500/day), Free User (10/day)
• Rank System — 4 tiers with auto-expiration for paid ranks
• BullMQ Queue — Priority-based job queue with concurrency control
• Rate Limiting — Redis-powered abuse protection (burst + cooldown)
• MSSQL Database — User management, usage tracking, generation history, guild management
• Image Storage — Organized by date (YYYY/MM/DD/) with metadata JSON
• Auto-Cleanup — Deletes images older than 30 days
• Statistics — Leaderboard, generation count, usage analytics
• Prompt Caching — Redis cache for repeated prompt+model combinations
• Graceful Shutdown — Clean cleanup of DB, Redis, and worker connections

🆕 Recent Updates (March 2026)

⭐ Major Features

• ✅ Seedream 5.0 Lite support with PNG output
• ✅ Sequential Image Generation (1-15 images in single API call)
• ✅ Output Format Options (PNG/JPEG selection)
• ✅ Optimization Modes (Standard/Fast for compatible models)
• ✅ Progress Tracking (Real-time download indicator)
• ✅ K-Format Sizes (1K, 2K, 3K, 4K presets)
• ✅ Guild Whitelist System (Database-managed authorization)
• ✅ Multi-Guild Deployment (Deploy to all authorized guilds at once)

🔧 Improvements

• Fixed dimension validation (K-format support, 3.68M pixel minimum)
• Modular seeddream.js architecture with private methods
• Model/format/optimization dropdown choices (no more text input)
• Enhanced deploy-commands.js (--global, --database, --clear flags)
• Better error messages and logging

📋 Database Changes

• New table: authorized_guilds (guild whitelist)
• Guild management queries added to queries.js

🎮 New Commands

• /admin-addguild — Add guild to whitelist
• /admin-removeguild — Remove guild from whitelist
• /admin-listguilds — View all authorized guilds

📁 Project Structure

├── commands/               # Slash commands
│   ├── generate.js         # Text-to-image generation (with format/optimize options)
│   ├── img2img.js          # Image-to-image transformation
│   ├── batchimg.js         # Batch image generation
│   ├── img2img-blending.js # Multi-image blending
│   ├── balance.js          # Check rank & remaining balance
│   ├── stats.js            # Statistics & leaderboard
│   └── admin/              # Admin-only commands
│       ├── setrank.js      # /admin-setrank
│       ├── extendrank.js   # /admin-extendrank
│       ├── resetlimit.js   # /admin-resetlimit
│       ├── addguild.js     # /admin-addguild (NEW)
│       ├── removeguild.js  # /admin-removeguild (NEW)
│       └── listguilds.js   # /admin-listguilds (NEW)
├── config/
│   └── config.js           # Centralized configuration (models, formats, optimization)
├── database/
│   ├── connection.js       # MSSQL connection pool
│   ├── queries.js          # All database operations (including guild management)
│   └── schema.sql          # Table creation DDL (includes authorized_guilds)
├── events/
│   └── interactionCreate.js # Command handler with guild authorization check
├── redis/
│   ├── redisClient.js      # Redis client, rate limiting, caching
│   └── queue.js            # BullMQ queue management
├── services/
│   ├── seeddream.js        # SeedDream API client (modular, supports all features)
│   ├── generationService.js # Generation orchestration with progress callbacks
│   ├── imageService.js     # Image saving & storage
│   ├── userService.js      # User management & rank expiration
│   └── limitService.js     # Daily limits & rate limiting
├── utils/
│   ├── logger.js           # File + console logging
│   ├── fileManager.js      # Date-based storage & cleanup
│   ├── validation.js       # Dimension & prompt validation (K-format support)
│   ├── dateHelper.js       # Date utilities
│   └── promptSanitizer.js  # Prompt cleaning
├── workers/
│   └── imageWorker.js      # BullMQ worker
├── storage/images/         # Generated images (auto-created)
├── logs/                   # Log files (auto-created)
├── index.js                # Main entry point
├── deploy-commands.js      # Command deployment script (--global, --database, --clear)
└── .env.example            # Environment template

Requirements

• Node.js >= 18.0.0
• MSSQL Server (SQL Server 2017+)
• Redis 6+
• Discord bot with applications.commands scope

Setup

1. Clone & Install

git clone https://github.com/your-username/discord-ai-bot.git
cd discord-ai-bot
npm install

2. Configure Environment

cp .env.example .env

Edit .env with your credentials:

Variable	Description	Default
DISCORD_TOKEN	Discord bot token	—
DISCORD_CLIENT_ID	Bot application client ID	—
GUILD_ID	Discord server ID (for dev deployment)	—
ADMIN_IDS	Comma-separated Discord user IDs for admins	—
ARK_API_URL	SeedDream API endpoint	—
ARK_API_KEY	SeedDream API key	—
API_TIMEOUT	API request timeout (ms)	300000
DEFAULT_WATERMARK	Enable/disable watermark	false
MAX_IMAGES	Maximum images per generation	15
DEFAULT_OUTPUT_FORMAT	Default output format (png/jpeg)	png
DEFAULT_OPTIMIZE_MODE	Default optimization mode (standard/fast)	standard
ENABLE_STREAMING	Enable streaming support (future)	false
DB_HOST	MSSQL server host	localhost
DB_PORT	MSSQL server port	1433
DB_NAME	Database name	ICC_DISCORD_AI
DB_USER	Database username	sa
DB_PASSWORD	Database password	—
REDIS_HOST	Redis server host	127.0.0.1
REDIS_PORT	Redis server port	6379
REDIS_PASSWORD	Redis password (optional)	—
STORAGE_PATH	Image storage directory	./storage/images

3. Initialize Database

Run the SQL schema on your MSSQL server:

# Execute database/schema.sql on your MSSQL instance

This creates 7 tables:

• users — User accounts with roles and ranks
• rank_limits — Daily generation limits per rank
• daily_usage — Daily usage tracking
• generation_history — Complete generation logs
• image_storage — Stored image metadata
• system_logs — System event logs
• authorized_guilds — Guild whitelist (NEW)

4. Deploy Slash Commands

Option 1: Deploy to single guild (instant, for development)

node deploy-commands.js

Option 2: Deploy to all authorized guilds in database

node deploy-commands.js --database

Option 3: Deploy globally to all guilds (takes up to 1 hour)

node deploy-commands.js --global

Option 4: Clear old commands before deploying

node deploy-commands.js --clear
# or combined:
node deploy-commands.js --database --clear

5. Start the Bot

npm start        # Production
npm run dev      # Development (with auto-reload)

🎮 Commands

User Commands

Command	Description	New Options
/generate	Generate AI image from text prompt	format, optimize, model (dropdown)
/img2img	Transform an existing image with AI	format, optimize, model
/batchimg	Generate multiple images at once	format, optimize, progress tracking
/img2img-blending	Blend 2-4 images together	format, optimize
/balance	Check your rank, limits, and remaining balance	—
/stats	View generation statistics and leaderboard	—

Command Options:

• model — Choose model: Seedream 5.0 Lite (default), 4.5, or 4.0
• aspect_ratio — Choose from presets: 1:1, 16:9, 2K, 3K, 4K, etc.
• custom_size — Custom resolution (e.g., 2048x2048 or 3K)
• count — Number of images (1-8 for generate, 1-10 for others)
• format — Output format: PNG or JPEG
• optimize — Speed optimization: Standard (better quality) or Fast

Progress Tracking: When generating multiple images, bot shows real-time progress:

⬇️ Downloading images (1/4)...
⬇️ Downloading images (2/4)...
✨ Generated 4 image(s)!

Admin Commands

Command	Description
/admin-setrank	Set a user's rank (0-3) with expiration date
/admin-extendrank	Extend a user's rank expiration
/admin-resetlimit	Reset a user's daily generation limit
/admin-addguild	Add a guild to authorized list ⭐ NEW
/admin-removeguild	Remove a guild from authorized list ⭐ NEW
/admin-listguilds	List all authorized guilds ⭐ NEW

Rank System

Rank	Daily Limit	Type
0	10	Free (default)
1	100	Paid
2	200	Paid
3	500	Paid
Admin	Unlimited	—

• New users automatically receive Rank 0
• Paid ranks (1+) have expiration dates
• Expired ranks auto-reset to Rank 0

🎨 Supported Models

Model	Supported Sizes	Output Formats	Optimization	Description
Seedream 5.0 Lite ⭐	2K, 3K	PNG, JPEG	Standard only	Latest model (default)
Seedream 4.5	2K, 4K	JPEG	Standard only	Higher quality
Seedream 4.0	1K, 2K, 4K	JPEG	Standard, Fast	More flexible

Resolution Formats:

• K-Format (recommended): 1K, 2K, 3K, 4K — API-optimized presets
• Pixel Format: 2048x2048, 3072x2048, etc. — Custom dimensions
• Aspect Ratios: 1:1, 4:3, 16:9, 21:9, etc. — Auto-converted to optimal resolution

Minimum Requirements:

• Images must be at least 3,686,400 pixels (~1920×1920)
• Maximum recommended: 4K (4096×4096)

🔐 Guild Authorization System

The bot uses a whitelist system — only authorized guilds can use commands.

Adding Guilds

Step 1: Add guild to database

/admin-addguild guild_id:123456789 guild_name:"My Server"

Step 2: Deploy commands to authorized guilds

node deploy-commands.js --database

Step 3: Users in that guild can now use the bot!

Managing Guilds

# View all authorized guilds
/admin-listguilds

# Remove a guild
/admin-removeguild guild_id:123456789

How it works:

• Commands check authorized_guilds table before executing
• Admin commands bypass the check
• Unauthorized guilds receive error message
• Changes take effect immediately (no restart needed)

🚀 Deployment Workflows

Development Environment

# Single guild deployment (instant)
node deploy-commands.js

# Test changes immediately in your dev server
npm run dev

Production Environment

# Deploy to all authorized guilds
node deploy-commands.js --database

# Or deploy globally (slower but automatic for all guilds)
node deploy-commands.js --global

# Start in production mode
npm start

Stuck Commands / Duplicates?

# Clear all commands and deploy fresh
node deploy-commands.js --database --clear

# Then reload Discord (Ctrl+R or Cmd+R)

🐛 Troubleshooting

Commands Not Showing in Discord

1. Verify deployment:

   node deploy-commands.js
   

   Output should show ✅ Successfully deployed X command(s)

2. Check guild authorization:

   /admin-listguilds
   

   Ensure your guild is in the list

3. Clear Discord cache:

   • Desktop: Press Ctrl+R (Windows) or Cmd+R (Mac)
   • Web: Hard refresh browser (Ctrl+Shift+R)

4. Check bot permissions:

   • Bot needs applications.commands scope
   • Reinvite with: https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=0&scope=bot%20applications.commands

API Errors

Error: "image size must be at least 3686400 pixels"

• ✅ Use K-format sizes: 2K, 3K, 4K
• ✅ Or ensure custom size ≥ 1920×1920
• ❌ Avoid very small resolutions

Error: "output image may contain sensitive information"

• Prompt triggered SeedDream's content filter
• Try rephrasing your prompt

Error: "No images were generated"

• Check bot logs for API errors
• Verify ARK_API_KEY is valid
• Check API endpoint URL

Database Connection Issues

# Test MSSQL connection
node -e "require('./database/connection').query('SELECT 1').then(() => console.log('✅ DB Connected')).catch(e => console.error('❌ DB Error:', e.message))"

Redis Connection Issues

# Check Redis is running
redis-cli ping
# Should return: PONG

# Or test from Node.js
node -e "require('./redis/redisClient').ping().then(() => console.log('✅ Redis Connected'))"

📝 License

MIT