Spaces:
Sleeping
Sleeping
| 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** | |
| [](https://www.gnu.org/licenses/agpl-3.0) | |
| [](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** | |