Gemini Balance is a Python FastAPI application designed to proxy and load balance Google Gemini API keys. It targets developers and users needing to manage multiple API keys, offering features like key rotation, authentication, model filtering, and status monitoring. The service provides a unified API endpoint compatible with both Gemini and OpenAI formats, enhancing usability and integration flexibility.

How It Works

The application leverages FastAPI for its asynchronous capabilities and performance. It manages a pool of Gemini API keys, distributing requests across them to improve availability and concurrency. Key features include automatic key failure detection, disabling of exhausted keys, and periodic re-enabling. It also supports image generation and various image hosting uploads, along with network search capabilities for supported models. The project offers an OpenAI-compatible API endpoint, facilitating seamless integration with existing OpenAI-based applications.

Quick Start & Requirements

• Docker:
  • Build image: docker build -t gemini-balance .
  • Run container: docker run -d -p 8000:8000 --env-file .env gemini-balance
  • Pull existing image: docker pull ghcr.io/snailyp/gemini-balance:latest
• Local:
  • Python 3.9+
  • Install dependencies: pip install -r requirements.txt
  • Run application: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
• Configuration: Requires an .env file with API_KEYS and ALLOWED_TOKENS.
• Docs: API Endpoints (within the README)

Highlighted Details

• Supports both Gemini and OpenAI API formats for chat, embeddings, and image generation.
• Features automatic key management with failure detection, retries, and scheduled recovery.
• Includes image generation capabilities (e.g., imagen-3.0-generate-002) and multiple image upload providers (SM.MS, PicGo, Cloudflare).
• Offers network search functionality for specified models and an optional stream optimizer for improved response experience.

Maintenance & Community

The project is actively maintained by snailyp. Contributions are welcomed via Pull Requests or Issues. Support for the project can be provided via "爱发电".

Licensing & Compatibility

The project is licensed under CC BY-NC 4.0 (Attribution-NonCommercial). This license strictly prohibits any commercial resale of the service.

Limitations & Caveats

The CC BY-NC 4.0 license restricts commercial use, meaning it cannot be used in commercial products or services. The README explicitly warns against commercial exploitation by others.