git404hub

what is gemini-balance fr?

snailyp/gemini-balance — explained in plain English

Analysis updated 2026-06-26

5,887PythonAudience · developerComplexity · 3/5LicenseSetup · moderate

tl;dr

A proxy server that pools multiple Google Gemini API keys and load-balances requests across them, so you can combine free-tier key limits into a single higher-capacity endpoint that also accepts OpenAI-compatible requests.

vibe map

mindmap
  root((gemini-balance))
    What it does
      Key rotation
      Load balancing
      Failover logic
    API formats
      Gemini native
      OpenAI-compatible
    Features
      Web search
      Image generation
      Admin dashboard
    Setup
      Docker
      SQLite or MySQL
      Env config

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

what do people make with this?

VIBE 1

Pool multiple free Gemini API keys to get higher combined rate limits for a personal or research project.

VIBE 2

Point any OpenAI-compatible tool or library at Gemini without rewriting any integration code.

VIBE 3

Monitor the health and status of multiple Gemini API keys from a single admin dashboard.

VIBE 4

Add web search or image generation capabilities to Gemini chat requests through one endpoint.

what's the stack?

PythonDockerMySQLSQLite

how it stacks up fr

snailyp/gemini-balancedpkp/kafka-pythonr0x0r/pywebview
Stars5,8875,8905,884
LanguagePythonPythonPython
Setup difficultymoderatemoderateeasy
Complexity3/53/52/5
Audiencedeveloperdeveloperdeveloper

Figures from each repo's GitHub metadata at analysis time.

how do i run it?

Difficulty · moderate time til it works · 30min

Requires Docker and either MySQL or SQLite, all Gemini API keys must be configured in an environment file before starting.

Creative Commons BY-NC 4.0, free for personal and educational use, but you cannot sell or commercially redistribute this service.

in plain english

Gemini Balance is a proxy server that sits between your application and Google's Gemini AI API. Its main job is to manage multiple Gemini API keys at once, cycling through them automatically so no single key takes all the load. If one key fails too many times, the service disables it and moves on. This is useful for developers or teams who have collected multiple free-tier API keys and want to pool their usage limits into a single endpoint. The service accepts requests in two formats: Google's own Gemini API format and the OpenAI-compatible API format. That second option matters because many tools and libraries are already built to talk to OpenAI, so this lets you point those tools at Gemini without rewriting any integration code. It covers chat, text embeddings, and image generation endpoints. Beyond key rotation, Gemini Balance adds features that the base Gemini API does not provide directly. It can attach web search to supported models, enable image generation and image editing through chat, and handle image uploads to external hosting services. There is also an admin web interface for managing configuration in real time without restarting the server, and a monitoring page for checking the status of all configured API keys. Setup is available through Docker (both AMD and ARM images are provided), Docker Compose, or a standard Python local install. Configuration lives in an environment file. The application needs either a MySQL or SQLite database to store logs and key status. The project is licensed under Creative Commons BY-NC 4.0, which allows free personal use but explicitly prohibits commercial resale. The README includes a note that the author has never sold this service and warns against resellers.

prompts (copy fr)

prompt 1
I have five free Gemini API keys and want to use gemini-balance to pool them. Write a docker-compose.yml that sets up the service with SQLite and show me the environment variables I need.
prompt 2
Using gemini-balance OpenAI-compatible endpoint, write a Python snippet using the openai library to send a chat message through Gemini.
prompt 3
How do I configure gemini-balance to automatically disable a Gemini API key after it fails three times in a row?
prompt 4
I want to monitor my Gemini API key statuses in gemini-balance. How do I access the admin panel and what can I configure there without restarting the server?

Frequently asked questions

what is gemini-balance fr?

A proxy server that pools multiple Google Gemini API keys and load-balances requests across them, so you can combine free-tier key limits into a single higher-capacity endpoint that also accepts OpenAI-compatible requests.

What language is gemini-balance written in?

Mainly Python. The stack also includes Python, Docker, MySQL.

What license does gemini-balance use?

Creative Commons BY-NC 4.0, free for personal and educational use, but you cannot sell or commercially redistribute this service.

How hard is gemini-balance to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is gemini-balance for?

Mainly developer.

peek the repo → explain another one

This repo across BitVibe Labs

double-check against the repo, no cap.