README.md

---
title: Character Forge
emoji: 🔥
colorFrom: red
colorTo: yellow
sdk: docker
pinned: false
license: agpl-3.0
app_port: 7860
---

# 🔥 Character Forge

**Professional AI Image Generation with Automated Character Sheets**

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
[![HuggingFace](https://img.shields.io/badge/🤗%20Hugging%20Face-Spaces-yellow)](https://huggingface.co/spaces/ghmk/character_forge)

---

## What is Character Forge?

Character Forge is a powerful AI image generation platform featuring:

✨ **Character Sheet Generation**: Transform a single image into a complete multi-angle character sheet automatically
🎬 **Composition Assistant**: Smart multi-image composition with auto-generated prompts
📸 **Standard Interface**: Direct text-to-image and image-to-image generation
📚 **Library Management**: Save and reuse characters, backgrounds, and styles
🔌 **Multi-Backend Support**: Use Gemini API (cloud) or run locally with ComfyUI

---

## 🚀 Quick Start

### Option 1: HuggingFace Spaces (Easiest)

Click the "Use this space" button on HuggingFace to deploy your own instance:

1. Fork/Duplicate this space
2. Go to Settings → Repository Secrets
3. Add your `GEMINI_API_KEY` (get one free at [Google AI Studio](https://aistudio.google.com/app/apikey))
4. Launch the space!

### Option 2: Local Installation

**Prerequisites:**
- Python 3.10 or higher
- Google Gemini API key (get it [here](https://aistudio.google.com/app/apikey))

**Installation:**

```bash
# Clone the repository
git clone https://github.com/yourusername/character-forge.git
cd character-forge

# Install dependencies
pip install -r requirements.txt

# Set your API key
export GEMINI_API_KEY="your-api-key-here"  # Linux/Mac
# OR
set GEMINI_API_KEY=your-api-key-here  # Windows

# Run the application
cd character_forge_image
streamlit run app.py
```

Open your browser to `http://localhost:8501`

---

## 🎯 Key Features

### 1. Character Forge

Transform ONE image into a complete character sheet:

- **2 Facial Views**: Front portrait + Side profile
- **3 Body Views**: Front + Side + Rear full body shots
- **Auto-Composited**: Single image ready for consistent character generation
- **Fast**: ~2-3 minutes, fully automated
- **Cost Effective**: ~$0.15 total for complete sheet (with Gemini API)

Perfect for:
- Game development
- Animation pipelines
- Consistent character generation
- Multi-character scenes

### 2. Composition Assistant

Intelligently compose multiple images:

- Upload 1-3 images
- Auto-detect image types (subject, background, style reference)
- AI-generated composition prompts
- Professional results with minimal manual work

### 3. Standard Interface

Direct image generation:

- Text-to-image
- Image-to-image transformation
- Multiple aspect ratios (1:1, 16:9, 9:16, 3:2, 2:3, 3:4, 4:3, 4:5, 5:4, 21:9)
- Temperature control for creativity vs consistency

### 4. Library Management

Build your asset library:

- Save generated characters
- Organize backgrounds and environments
- Store style references
- Quick access for future compositions

---

## 🔧 Backend Options

### Gemini API (Cloud) - Default

**Best for getting started:**
- No local installation needed
- High quality results
- ~$0.03 per image
- Free tier available

**Setup:**
1. Get API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
2. Set as environment variable or enter in UI
3. Start generating!

### ComfyUI (Local) - Advanced

**For power users:**
- Complete control
- No per-image costs
- GPU required
- Advanced workflows supported

**Setup:** See [COMFYUI_SETUP.md](docs/COMFYUI_SETUP.md)

---

## 📖 Documentation

- **Quick Start Guide**: You're reading it!
- **Character Sheet Tutorial**: [docs/CHARACTER_SHEETS.md](docs/CHARACTER_SHEETS.md)
- **Composition Guide**: [docs/COMPOSITION_ASSISTANT.md](docs/COMPOSITION_ASSISTANT.md)
- **ComfyUI Integration**: [docs/COMFYUI_SETUP.md](docs/COMFYUI_SETUP.md)
- **API Reference**: [docs/API.md](docs/API.md)

---

## 💡 Tips for Best Results

### Character Sheets
- Use clear, well-lit source images
- Front-facing photos work best
- Simple backgrounds preferred
- High resolution helps (but not required)

### Composition
- Generate subjects separately from backgrounds
- Use consistent lighting across images
- Be specific in your prompts
- Experiment with temperature settings

### General
- **Temperature 0.0-0.3**: Conservative, consistent
- **Temperature 0.4-0.6**: Balanced (recommended)
- **Temperature 0.7-1.0**: Creative, varied

---

## 🤝 Contributing

Contributions are welcome! Please feel free to:

- Report bugs
- Suggest features
- Submit pull requests
- Improve documentation

---

## 📝 License

GNU Affero General Public License v3.0 (AGPL-3.0)

**What this means:**

✓ **Free to use**: Personal, educational, and research use is completely free
✓ **Your content is yours**: Images and characters you generate belong to you
✓ **Modify freely**: You can modify and improve the software
✓ **Share improvements**: Modified versions must also be open source

✗ **No proprietary integration**: Cannot be integrated into closed-source commercial products
✗ **Network use = source sharing**: If you run this as a service, you must share your source code

**For commercial services or products**, any modifications or integrations must be released
under AGPL-3.0. This ensures the software remains free and open for everyone.

**For generated content**: Your images, characters, and creative outputs are yours to use
however you want - commercially or otherwise. The AGPL only applies to the software itself.

See [LICENSE](LICENSE) for full details and [NOTICE](NOTICE) for important information.

For commercial licensing inquiries or questions, please contact the authors.
## 🙏 Acknowledgments

- Google for the Gemini 2.5 Flash Image API
- Streamlit for the excellent UI framework
- The ComfyUI community
- All contributors and users

---

## 🔗 Links

- **Documentation**: [Full documentation](docs/)
- **Google Gemini API**: https://ai.google.dev/
- **Streamlit**: https://streamlit.app/
- **Report Issues**: [GitHub Issues](https://github.com/yourusername/character-forge/issues)

---

## ❓ FAQ

**Q: How much does it cost?**
A: With Gemini API: ~$0.03 per image. Free tier available for testing.

**Q: Do I need a GPU?**
A: Only for local ComfyUI backend. Gemini API runs in the cloud.

**Q: Can I use this commercially?**
A: Generated images are yours to use commercially. The software code must remain open source (AGPL).

**Q: Is my data private?**
A: With Gemini API, images are processed by Google. For complete privacy, use ComfyUI locally.

**Q: What image formats are supported?**
A: PNG, JPEG, WebP for input and output.

---

**Made with ❤️ by the Character Forge team**