Spaces:

ghmk
/

character_forge

Sleeping

App Files Files Community

character_forge / README.md

ghmk

Fix colorTo in metadata (orange -> yellow)

e494e0c 3 months ago

preview code

raw

history blame contribute delete

6.89 kB

metadata

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

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:

Fork/Duplicate this space
Go to Settings → Repository Secrets
Add your GEMINI_API_KEY (get one free at Google AI Studio)
Launch the space!

Option 2: Local Installation

Prerequisites:

Python 3.10 or higher
Google Gemini API key (get it here)

Installation:

# 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:

Get API key from Google AI Studio
Set as environment variable or enter in UI
Start generating!

ComfyUI (Local) - Advanced

For power users:

Complete control
No per-image costs
GPU required
Advanced workflows supported

Setup: See COMFYUI_SETUP.md

📖 Documentation

Quick Start Guide: You're reading it!
Character Sheet Tutorial: docs/CHARACTER_SHEETS.md
Composition Guide: docs/COMPOSITION_ASSISTANT.md
ComfyUI Integration: docs/COMFYUI_SETUP.md
API Reference: 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 for full details and 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
Google Gemini API: https://ai.google.dev/
Streamlit: https://streamlit.app/
Report Issues: GitHub 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