docs/SETUP_MULTIPLE_API_KEYS.md

How to Use Multiple API Keys

Quick Setup Guide

Step 1: Set Environment Variables

You can set multiple API keys. The system loads them in order:

• GEMINI_API_KEY → Index 0 (base key)
• GEMINI_API_KEY_1 → Index 1
• GEMINI_API_KEY_2 → Index 2
• And so on...

For Gemini API (Google AI)

# Linux/Mac
export GEMINI_API_KEY="AIzaSyAbc123..."      # Index 0 (base)
export GEMINI_API_KEY_1="AIzaSyDef456..."    # Index 1
export GEMINI_API_KEY_2="AIzaSyGhi789..."    # Index 2
export GEMINI_API_KEY_3="AIzaSyJkl012..."    # Index 3

# Windows (Command Prompt)
set GEMINI_API_KEY_1=AIzaSyAbc123...
set GEMINI_API_KEY_2=AIzaSyDef456...
set GEMINI_API_KEY_3=AIzaSyGhi789...

# Windows (PowerShell)
$env:GEMINI_API_KEY_1="AIzaSyAbc123..."
$env:GEMINI_API_KEY_2="AIzaSyDef456..."
$env:GEMINI_API_KEY_3="AIzaSyGhi789..."

For NVIDIA API

# Linux/Mac
export NVIDIA_API_KEY_1="nvapi-abc123..."
export NVIDIA_API_KEY_2="nvapi-def456..."
export NVIDIA_API_KEY_3="nvapi-ghi789..."

# Windows (Command Prompt)
set NVIDIA_API_KEY_1=nvapi-abc123...
set NVIDIA_API_KEY_2=nvapi-def456...

# Windows (PowerShell)
$env:NVIDIA_API_KEY_1="nvapi-abc123..."
$env:NVIDIA_API_KEY_2="nvapi-def456..."

For OpenRouter API (Amazon Nova)

# Linux/Mac
export OPENROUTER_API_KEY_1="sk-or-v1-abc123..."
export OPENROUTER_API_KEY_2="sk-or-v1-def456..."
export OPENROUTER_API_KEY_3="sk-or-v1-ghi789..."

# Windows (Command Prompt)
set OPENROUTER_API_KEY_1=sk-or-v1-abc123...
set OPENROUTER_API_KEY_2=sk-or-v1-def456...

# Windows (PowerShell)
$env:OPENROUTER_API_KEY_1="sk-or-v1-abc123..."
$env:OPENROUTER_API_KEY_2="sk-or-v1-def456..."

Step 2: Using .env File (Recommended - Already Configured!)

✅ Good news: The app already has .env support built-in!

Just create a .env file in your project root:

# .env file
# Gemini API Keys (get from: https://aistudio.google.com/app/apikey)
GEMINI_API_KEY=AIzaSyAbc123...      # Index 0 (base key)
GEMINI_API_KEY_1=AIzaSyDef456...    # Index 1
GEMINI_API_KEY_2=AIzaSyGhi789...    # Index 2

# NVIDIA API Keys (get from: https://build.nvidia.com/)
NVIDIA_API_KEY=nvapi-abc123...      # Index 0 (base key)
NVIDIA_API_KEY_1=nvapi-def456...    # Index 1

# OpenRouter API Keys (get from: https://openrouter.ai/keys)
OPENROUTER_API_KEY=sk-or-v1-abc123...    # Index 0 (base key)
OPENROUTER_API_KEY_1=sk-or-v1-def456...  # Index 1

That's it! Just run the app normally:

python3 run.py

The .env file is automatically loaded. No extra steps needed!

Quick Start:

# 1. Copy the example file
cp .env.example .env

# 2. Edit .env and add your API keys
nano .env

# 3. Run the app
python3 run.py

Step 3: Verify Keys Are Loaded

Run this to check if your keys are loaded correctly:

python3 -c "
from api_key_manager import get_api_key_manager

manager = get_api_key_manager()
status = manager.get_all_services_status()

for service, info in status.items():
    print(f'{service.upper()}: {info[\"total_keys\"]} key(s) loaded')
"

Expected output:

NVIDIA: 2 key(s) loaded
GEMINI: 3 key(s) loaded
OPENROUTER: 2 key(s) loaded

---

How It Works

Automatic Rotation

Once you have multiple keys configured, the system automatically:

1. Rotates through them (round-robin)
2. Fails over when one key fails
3. Blocks keys that fail 3 times (for 5 minutes)
4. Unblocks keys after cooldown
5. Tracks success rates for each key

Example Flow

Let's say you have 3 Gemini keys configured:

Request 1 → Uses Key 1 ✓
Request 2 → Uses Key 2 ✓
Request 3 → Uses Key 3 ✓
Request 4 → Uses Key 1 ✓ (rotation back to start)
Request 5 → Uses Key 2 ✗ (fails - rate limit)
Request 6 → Uses Key 3 ✓ (automatically switched)
Request 7 → Uses Key 1 ✓
Request 8 → Uses Key 2 ✗ (fails again - 2nd failure)
Request 9 → Uses Key 3 ✓ (automatically switched)
Request 10 → Uses Key 2 ✗ (fails again - 3rd failure, BLOCKED)
Request 11 → Uses Key 3 ✓ (Key 2 is skipped)
Request 12 → Uses Key 1 ✓
Request 13 → Uses Key 3 ✓ (Key 2 still blocked)
... 5 minutes later ...
Request N → Uses Key 2 ✓ (unblocked and back in rotation)

---

Getting API Keys

Gemini API (Google AI)

1. Go to https://aistudio.google.com/app/apikey
2. Click "Create API Key"
3. Copy the key (starts with AIzaSy...)
4. Tip: Create multiple keys from different Google accounts for more quota

NVIDIA API

1. Go to https://build.nvidia.com/
2. Sign in and navigate to API Keys
3. Generate a new API key
4. Copy the key (starts with nvapi-...)

OpenRouter API

1. Go to https://openrouter.ai/keys
2. Sign up and create an API key
3. Copy the key (starts with sk-or-v1-...)
4. Tip: OpenRouter gives free credits for Nova model

---

Common Scenarios

Scenario 1: Maximize Free Tier Usage

If you have multiple Google accounts, create one Gemini API key from each:

export GEMINI_API_KEY="key-from-account-1"      # Index 0
export GEMINI_API_KEY_1="key-from-account-2"    # Index 1
export GEMINI_API_KEY_2="key-from-account-3"    # Index 2
export GEMINI_API_KEY_3="key-from-account-4"    # Index 3

This gives you 4x the free tier quota!

Scenario 2: Paid + Free Keys

Mix paid and free keys:

export GEMINI_API_KEY="paid-key-with-high-quota"    # Index 0 - tried first
export GEMINI_API_KEY_1="free-key-1"                # Index 1 - backup
export GEMINI_API_KEY_2="free-key-2"                # Index 2 - backup

The system will rotate through all of them, maximizing your available quota.

Scenario 3: Single Key (Backward Compatible)

If you only have one key, the old method still works:

export GEMINI_API_KEY="your-single-key"

The system will use this single key without rotation.

---

Troubleshooting

Problem: Keys not being loaded

Check:

1. Environment variables are set in the same terminal/session where you run the app
2. Variable names match exactly (case-sensitive)
3. No extra spaces in variable values

Test:

# Linux/Mac
echo $GEMINI_API_KEY_1
echo $GEMINI_API_KEY_2

# Windows (Command Prompt)
echo %GEMINI_API_KEY_1%
echo %GEMINI_API_KEY_2%

# Windows (PowerShell)
echo $env:GEMINI_API_KEY_1
echo $env:GEMINI_API_KEY_2

Problem: Only first key is being used

Likely cause: Other keys aren't set properly.

Fix: Verify all keys are loaded:

import os
print("Key 1:", os.environ.get('GEMINI_API_KEY_1'))
print("Key 2:", os.environ.get('GEMINI_API_KEY_2'))
print("Key 3:", os.environ.get('GEMINI_API_KEY_3'))

Problem: All keys get blocked quickly

Causes:

• Invalid API keys
• Insufficient quota/rate limits
• API service issues

Fix:

1. Verify each key works individually
2. Check your quota limits with the API provider
3. Add more keys to distribute the load
4. Increase wait times between requests

---

Best Practices

✅ Use at least 2-3 keys per service for reliability
✅ Get keys from different accounts to maximize free tier
✅ Keep backup keys from different providers if possible
✅ Monitor key usage to identify which ones work best
✅ Store keys securely in .env file (add to .gitignore)
✅ Don't commit keys to git - use environment variables
✅ Rotate keys periodically for security

---

Advanced: Persistent Configuration

To make environment variables persist across reboots:

Linux/Mac - Add to ~/.bashrc or ~/.zshrc:

export GEMINI_API_KEY_1="..."
export GEMINI_API_KEY_2="..."
export GEMINI_API_KEY_3="..."

Then reload: source ~/.bashrc

Windows - Use System Environment Variables:

1. Search for "Environment Variables" in Start Menu
2. Click "Edit system environment variables"
3. Click "Environment Variables" button
4. Add your keys under "User variables"

---

Summary

To use multiple API keys:

1. Set numbered environment variables:

   • GEMINI_API_KEY_1, GEMINI_API_KEY_2, etc.
   • NVIDIA_API_KEY_1, NVIDIA_API_KEY_2, etc.
   • OPENROUTER_API_KEY_1, OPENROUTER_API_KEY_2, etc.

2. That's it! The system automatically:

   • Loads all keys
   • Rotates through them
   • Handles failures
   • Maximizes availability

No code changes needed - just set the environment variables and the API Key Manager handles everything!