Read this document in Chinese

Gemini Balance - Gemini API Proxy and Load Balancer

⚠️ Important: This project is licensed under the CC BY-NC 4.0 license. Any form of commercial resale service is prohibited. I have never sold this service on any platform. If you encounter someone selling this service, they are a reseller. Please do not be deceived.

📖 Project Introduction

Gemini Balance is an application built with Python FastAPI, designed to provide proxy and load balancing functions for the Google Gemini API. It allows you to manage multiple Gemini API Keys and implement key rotation, authentication, model filtering, and status monitoring through simple configuration. Additionally, the project integrates image generation and multiple image hosting upload functions, and supports proxying in the OpenAI API format.

app/
├── config/       # Configuration management
├── core/         # Core application logic (FastAPI instance creation, middleware, etc.)
├── database/     # Database models and connections
├── domain/       # Business domain objects
├── exception/    # Custom exceptions
├── handler/      # Request handlers
├── log/          # Logging configuration
├── main.py       # Application entry point
├── middleware/   # FastAPI middleware
├── router/       # API routes (Gemini, OpenAI, status page, etc.)
├── scheduler/    # Scheduled tasks (e.g., Key status check)
├── service/      # Business logic services (chat, Key management, statistics, etc.)
├── static/       # Static files (CSS, JS)
├── templates/    # HTML templates (e.g., Key status page)
└── utils/        # Utility functions

✨ Feature Highlights

• Multi-Key Load Balancing: Supports configuring multiple Gemini API Keys (API_KEYS) for automatic sequential polling.
• Visual Configuration: Configurations modified through the admin backend take effect immediately without restarting.
• Dual Protocol API Compatibility: Supports both Gemini and OpenAI CHAT API formats.
  • OpenAI Base URL: http://localhost:8000(/hf)/v1
  • Gemini Base URL: http://localhost:8000(/gemini)/v1beta
• Image-Text Chat & Modification: Configure models with IMAGE_MODELS to support image-text chat and editing. Use the configured_model-image model name to invoke.
• Web Search: Configure models with SEARCH_MODELS to support web search. Use the configured_model-search model name to invoke.
• Key Status Monitoring: Provides a /keys_status page (authentication required) for real-time monitoring.
• Detailed Logging: Provides detailed error logs for easy troubleshooting.
• Flexible Key Addition: Add keys in batches using the gemini_key regex, with automatic deduplication.
• Failure Retry & Auto-Disable: Automatically retries failed API requests (MAX_RETRIES) and disables keys after excessive failures (MAX_FAILURES).
• Comprehensive API Compatibility:
  • Embeddings API: Fully compatible with the OpenAI embeddings API format.
  • Image Generation API: Adapts the imagen-3.0-generate-002 model to the OpenAI image generation API format.
• Automatic Model List Maintenance: Automatically fetches and syncs the latest model lists from Gemini and OpenAI.
• Proxy Support: Supports HTTP/SOCKS5 proxies (PROXIES).
• Docker Support: Provides Docker images for both AMD and ARM architectures.
  • Image Address: ghcr.io/snailyp/gemini-balance:latest

🚀 Quick Start

Option 1: Docker Compose (Recommended)

1. Get docker-compose.yml: Download the docker-compose.yml file from the project repository.
2. Prepare .env file: Copy .env.example to .env and configure it. Ensure DATABASE_TYPE is set to mysql and fill in the MYSQL_* details.
3. Start Services: In the directory containing docker-compose.yml and .env, run:

   docker-compose up -d
   

Option 2: Docker Command

1. Pull Image:

   docker pull ghcr.io/snailyp/gemini-balance:latest
   

2. Prepare .env file: Copy .env.example to .env and configure it.
3. Run Container:

   docker run -d -p 8000:8000 --name gemini-balance \
   -v ./data:/app/data \
   --env-file .env \
   ghcr.io/snailyp/gemini-balance:latest
   

   • -d: Detached mode.
   • -p 8000:8000: Map container port 8000 to host.
   • -v ./data:/app/data: Mount volume for persistent data.
   • --env-file .env: Load environment variables.

Option 3: Local Development

1. Clone and Install:

   git clone https://github.com/snailyp/gemini-balance.git
   cd gemini-balance
   pip install -r requirements.txt
   

2. Configure Environment: Copy .env.example to .env and configure it.
3. Start Application:

   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
   

   Access the application at http://localhost:8000.

⚙️ API Endpoints

Gemini API Format (/gemini/v1beta)

This endpoint is directly forwarded to official Gemini API format endpoint, without advanced features.

• GET /models: List available Gemini models.
• POST /models/{model_name}:generateContent: Generate content.
• POST /models/{model_name}:streamGenerateContent: Stream content generation.

OpenAI API Format

Hugging Face (HF) Compatible

If you want to use advanced features, like fake streaming, please use this endpoint.

• GET /hf/v1/models: List models.
• POST /hf/v1/chat/completions: Chat completion.
• POST /hf/v1/embeddings: Create text embeddings.
• POST /hf/v1/images/generations: Generate images.

Standard OpenAI

This endpoint is directly forwarded to official OpenAI Compatible API format endpoint, without advanced features.

• GET /openai/v1/models: List models.
• POST /openai/v1/chat/completions: Chat completion (Recommended).
• POST /openai/v1/embeddings: Create text embeddings.
• POST /openai/v1/images/generations: Generate images.

🤝 Contributing

Pull Requests or Issues are welcome.

⭐ Star History

🎉 Special Thanks

• PicGo
• SM.MS
• CloudFlare-ImgBed

🙏 Our Supporters

A special shout-out to DigitalOcean for providing the rock-solid and dependable cloud infrastructure that keeps this project humming!

CDN acceleration and security protection for this project are sponsored by Tencent EdgeOne.

💖 Friendly Projects

• OneLine by chengtx809 - AI-driven hot event timeline generation tool.

🎁 Project Support

If you find this project helpful, consider supporting me via Afdian.

License

This project is licensed under the CC BY-NC 4.0 (Attribution-NonCommercial) license.