Hugging Face's logo

Spaces:
ghmk
/
character_forge
Sleeping

App Files Community
character_forge / docs /QUICK_START.md
ghmk's picture
ghmk
Initial deployment of Character Forge
5b6e956
preview code
|
raw
history blame contribute delete
5.25 kB

Quick Start Guide

Get up and running with Character Forge in 5 minutes!

Step 1: Get Your API Key

  1. Visit https://aistudio.google.com/app/apikey
  2. Sign in with your Google account
  3. Click "Create API Key" → "Create API key in new project"
  4. Copy your key (starts with AIzaSy...)
  5. Keep it safe and secret!

Cost: ~$0.03 per image | Free tier available

Step 2: Choose Your Installation

Option A: Local Installation (Recommended)

Windows:

# Install
install.bat

# Set your API key
set GEMINI_API_KEY=your-key-here

# Run
start.bat

Linux/Mac:

# Install
chmod +x install.sh
./install.sh

# Set your API key
export GEMINI_API_KEY=your-key-here

# Run
chmod +x start.sh
./start.sh

Open browser: http://localhost:8501

Option B: HuggingFace Spaces (Online)

  1. Go to https://huggingface.co/spaces
  2. Click "Create new Space"
  3. Upload Character Forge files
  4. Add API key in Repository Secrets
  5. Launch!

See: HUGGINGFACE_DEPLOYMENT.md for detailed instructions

Step 3: Create Your First Character Sheet

  1. Open the app (localhost:8501 or your HF Space)
  2. Click "🔥 Character Forge" in the sidebar
  3. Upload a clear photo (face or full body)
  4. Click "Generate Character Sheet"
  5. Wait 2-3 minutes
  6. Download your complete character sheet!

Result: 5 professionally composed views of your character

Step 4: Use Your Character Sheet

Your character sheet can be used for:

  • ✅ Consistent character generation in new scenes
  • ✅ Multi-character compositions
  • ✅ Animation reference
  • ✅ Game development
  • ✅ Storyboarding

Features Overview

🔥 Character Forge

Create complete character sheets from one image

  • Upload 1 image → Get 5 views
  • Front/side faces + front/side/back body
  • Auto-composited into single sheet
  • 2-3 minutes total time

🎬 Composition Assistant

Smart multi-image composition

  • Upload 1-3 images
  • Auto-detection of image types
  • AI-generated composition prompts
  • Professional results

📸 Standard Interface

Direct image generation

  • Text-to-image
  • Image-to-image
  • Multiple aspect ratios
  • Temperature control

📚 Library

Save and organize your assets

  • Characters
  • Backgrounds
  • Styles
  • Quick reuse

Tips for Success

For Character Sheets

✅ DO:

  • Use clear, well-lit photos
  • Front-facing works best
  • Simple backgrounds preferred
  • High resolution helps

❌ DON'T:

  • Use blurry images
  • Too much background clutter
  • Extreme angles
  • Multiple people in frame

For Best Quality

Temperature Settings:

  • 0.0-0.3: Consistent, follows prompt closely
  • 0.4-0.6: Balanced (recommended)
  • 0.7-1.0: Creative, more variation

Prompts:

  • Be specific and descriptive
  • Include style keywords ("photorealistic", "digital art")
  • Mention lighting and composition
  • Add detail about mood and atmosphere

Cost Management

Optimize your usage:

  • Preview before generating
  • Use lower temperature for consistency (fewer retries)
  • Batch similar tasks together
  • Save good results to library for reuse

Typical costs with Gemini API:

  • Single image: ~$0.03
  • Character sheet: ~$0.15 (5 images)
  • Composition: ~$0.03-0.06 (1-2 images)

Common Use Cases

Game Development

  1. Create character sheets for all NPCs
  2. Generate environment backgrounds
  3. Create texture variations
  4. Compose characters into scenes

Animation

  1. Generate character reference sheets
  2. Create background art
  3. Develop style references
  4. Storyboard scene composition

Creative Projects

  1. Illustrate stories
  2. Concept art development
  3. Visual worldbuilding
  4. Character design iteration

Troubleshooting

"API Key Not Set"

Solution:

  • Set environment variable before running
  • OR enter key in sidebar when app starts
  • OR use HF Spaces Repository Secrets

"Generation Failed"

Possible causes:

  • Content policy violation (try rephrasing)
  • Rate limit (wait a moment)
  • Network issue (check connection)
  • Invalid API key (verify it's correct)

Try:

  1. Rephrase your prompt
  2. Adjust temperature
  3. Try a different image
  4. Check API key is valid

"Slow Generation"

Normal timing:

  • Single image: 10-30 seconds
  • Character sheet: 2-3 minutes
  • Composition: 20-60 seconds

If slower:

  • Check internet connection
  • Verify API quota not exceeded
  • Try during off-peak hours

Port Already in Use

Solution:

# Kill existing process
# Windows:
taskkill /IM streamlit.exe /F

# Linux/Mac:
pkill -f streamlit

Or edit app.py to use different port.

Next Steps

Now that you're set up:

  1. ✅ Generate your first character sheet
  2. ✅ Try the composition assistant
  3. ✅ Experiment with different temperatures
  4. ✅ Build your asset library
  5. ✅ Integrate into your workflow

Need Help?

  • Documentation: See /docs folder
  • Examples: Check the workflow examples
  • Issues: Report on GitHub
  • API Help: https://ai.google.dev/

Resources

Happy Creating! 🎨