docs/QUICK_START.md

# 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:**
```cmd
# Install
install.bat

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

# Run
start.bat
```

**Linux/Mac:**
```bash
# 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](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:**
```bash
# 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

- **Gemini API Docs**: https://ai.google.dev/
- **Streamlit Docs**: https://docs.streamlit.io/
- **HuggingFace Spaces**: https://huggingface.co/docs/hub/spaces

---

**Happy Creating! 🎨**