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

set GEMINI_API_KEY=AIzaSy...your_key_here

Windows (PowerShell):

$env:GEMINI_API_KEY="AIzaSy...your_key_here"

Linux/Mac:

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:

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! 🔑