docs/API_KEY_SETUP.md

# Google Gemini API Key Setup

Complete guide to getting and using your free Google Gemini API key.

## Why Do You Need an API Key?

Character Forge uses Google's Gemini 2.5 Flash Image API for AI image generation. You need an API key to:

- Authenticate your requests
- Track usage and costs
- Access the service

## Step 1: Create Your API Key

### Visit Google AI Studio

1. Go to https://aistudio.google.com/app/apikey
2. Sign in with your Google account
3. Accept the terms of service (if prompted)

### Create API Key

1. Click **"Create API Key"**
2. Choose **"Create API key in new project"**
   - Or select an existing Google Cloud project
3. Wait a few seconds for creation
4. Your key will appear (starts with `AIzaSy...`)

### Copy Your Key

1. Click the copy icon next to your key
2. Store it somewhere safe
3. **IMPORTANT**: Never share this key publicly!

## Step 2: Use Your API Key

You have several options:

### Option A: Environment Variable (Recommended for Local)

**Windows (Command Prompt):**
```cmd
set GEMINI_API_KEY=AIzaSy...your_key_here
```

**Windows (PowerShell):**
```powershell
$env:GEMINI_API_KEY="AIzaSy...your_key_here"
```

**Linux/Mac:**
```bash
export GEMINI_API_KEY=AIzaSy...your_key_here
```

**Make it permanent:**

**Windows:**
1. System Properties → Environment Variables
2. Add new user variable
3. Name: `GEMINI_API_KEY`
4. Value: Your key

**Linux/Mac:**
Add to `~/.bashrc` or `~/.zshrc`:
```bash
export GEMINI_API_KEY=AIzaSy...your_key_here
```

### Option B: In the UI

1. Start the app
2. Look in the sidebar
3. Find "Gemini API Key" input
4. Paste your key
5. Continue using the app

**Note**: This is temporary, key won't persist after restart

### Option C: HuggingFace Secrets (For HF Spaces)

1. Go to your Space settings
2. Click "Repository secrets"
3. Add new secret:
   - Name: `GEMINI_API_KEY`
   - Value: Your API key
4. Save

**The app will automatically use this secret**

## Step 3: Verify It Works

### Test in the App

1. Start Character Forge
2. Backend selector should show "Gemini API (Cloud)" with a ✅
3. Try generating a simple image
4. If it works, you're all set!

### Check Status

In the app:
- Green checkmark (✅) = API key is valid
- Red X (❌) = API key missing or invalid
- Yellow warning (⚠️) = API key not tested

## Understanding Costs

### Pricing (as of January 2025)

**Gemini 2.5 Flash Image:**
- ~$0.03 per image generation
- Exact pricing at: https://ai.google.dev/pricing

**Free Tier:**
- 15 requests per minute
- 1,500 requests per day
- Good for testing and personal use

### Cost Examples

| Task | Images | Cost |
|------|--------|------|
| Single image | 1 | ~$0.03 |
| Character sheet | 5 | ~$0.15 |
| Composition | 1-2 | ~$0.03-0.06 |
| 100 images | 100 | ~$3.00 |

### Monitoring Usage

**Check your usage:**
1. Go to https://aistudio.google.com/
2. Click on your project
3. View quotas and usage

**Set up billing alerts:**
1. Go to Google Cloud Console
2. Set up budget alerts
3. Get notified when approaching limits

## Security Best Practices

### ✅ DO

- Store key in environment variables
- Use Secrets for HuggingFace Spaces
- Keep key private and secret
- Rotate key if compromised
- Monitor usage regularly

### ❌ DON'T

- Commit key to Git repositories
- Share key publicly
- Hardcode key in your code
- Upload key in screenshots
- Email key in plain text

### If Key is Compromised

1. Go to https://aistudio.google.com/app/apikey
2. Find your compromised key
3. Click delete/revoke
4. Create a new key
5. Update your applications

## Troubleshooting

### "API Key Not Set"

**Check:**
- Environment variable is set correctly
- Key is spelled exactly right (case-sensitive)
- No extra spaces before/after key
- You've restarted terminal/app after setting

**Try:**
- Set it directly in the UI
- Verify key at https://aistudio.google.com/app/apikey

### "Invalid API Key"

**Causes:**
- Key was revoked
- Key has typo
- Project was deleted
- Billing not set up (for paid features)

**Solution:**
1. Verify key at Google AI Studio
2. Create new key if needed
3. Update your configuration

### "Quota Exceeded"

**Free tier limits:**
- 15 requests/minute
- 1,500 requests/day

**Solutions:**
- Wait for quota to reset
- Reduce generation frequency
- Upgrade to paid tier

**Check quotas:**
https://aistudio.google.com/ → Your project → Quotas

### "Billing Required"

**If you hit free tier limits:**
1. Go to Google Cloud Console
2. Enable billing for your project
3. Set up payment method
4. Set budget alerts

**Don't worry**: You can set spending limits!

## Advanced: Multiple Keys

### For Team Use

Create separate keys for:
- Development
- Testing
- Production
- Different team members

**Benefits:**
- Track usage separately
- Revoke individual keys
- Better security

### Rotating Keys

**Best practice:**
1. Create new key
2. Update applications
3. Test everything works
4. Delete old key

**Do this:**
- Periodically (every 90 days)
- If team members leave
- If key might be compromised

## API Limits Reference

### Rate Limits (Free Tier)

- **Requests per minute**: 15
- **Requests per day**: 1,500
- **Concurrent requests**: 5

### Rate Limits (Paid)

- Higher limits available
- Contact Google for enterprise limits
- Custom quotas possible

### Image Limits

- **Max file size**: 20 MB
- **Max images per request**: 3 (for composition)
- **Supported formats**: PNG, JPEG, WebP

## FAQ

**Q: Is the API key free?**
A: Yes! Free tier includes 1,500 requests/day. Paid tiers available for more.

**Q: How long does the key last?**
A: Indefinitely, until you revoke it. But rotate regularly for security.

**Q: Can I use one key for multiple apps?**
A: Yes, but separate keys are better for tracking and security.

**Q: What if I lose my key?**
A: Create a new one at https://aistudio.google.com/app/apikey

**Q: Can I share my key with my team?**
A: Not recommended. Create separate keys or use service accounts.

**Q: Does the key expire?**
A: No automatic expiration, but revoke and recreate periodically.

**Q: What happens if I go over free tier?**
A: Requests will fail. Set up billing to continue, or wait for reset.

## Getting Help

**Google AI Studio:**
- Docs: https://ai.google.dev/
- Support: https://support.google.com/

**Character Forge:**
- Documentation: See `/docs` folder
- Issues: Report on GitHub

---

**Keep your key safe and happy generating! 🔑**