This project provides a lightweight, Deno-based server that acts as a proxy to the Google Gemini API. It intelligently rotates a pool of API keys to help manage rate limits and prevent service interruptions.
- Table of contents
- Requirements
- Getting Started
- Configuration
- Features at a glance
- Built with
- Contributing
- Getting help
This project requires Deno to run. For development, you will also need Node.js 18 or higher.
There are two ways to use this project: deploying it to Deno Deploy or running it locally.
- Fork this repository.
- Go to Deno Deploy and create a new project.
- Link your GitHub account and select your forked repository.
- In the project settings, add your environment variables (see Configuration).
- Deploy! Your Gemini Key Rotator is now live.
-
Clone the repository:
git clone https://github.com/satusdev/gemeni-key-rotator.git cd gemeni-key-rotator -
Set up environment variables:
Create a
.envfile by copying the example:cp .env.example .env
Then, edit the
.envfile to add your API keys. -
Run the server:
deno run --allow-env --allow-net --allow-read mod.ts
Your proxy will be running at
http://localhost:8000.curl -X POST "http://localhost:8000/v1beta/models/gemini-2.5-pro:generateContent" \ -H "Content-Type: application/json" \ -d '{ "contents": [{ "parts":[{ "text": "Write a story about a magic backpack." }] }] }'
Invoke-WebRequest -Uri "http://localhost:8000/v1beta/models/gemini-2.5-pro:generateContent" ` -Method POST ` -Headers @{"Content-Type"="application/json"} ` -Body '{"contents":[{"parts":[{"text": "Write a story about a magic backpack."}]}]}'
This project is configured through environment variables. See .env.example for
all available options.
API_KEYS: A comma-separated list of your Gemini API keys.
GEMINI_API_BASE_URL: The base URL for the Gemini API. Defaults tohttps://generativelanguage.googleapis.com.
- API Key Rotation: Automatically rotates through a list of API keys to distribute requests.
- Rate Limiting: Basic IP-based rate limiting to prevent abuse.
- Cooldowns: When an API key hits a rate limit (429) or encounters a server error (5xx), it's put on a cooldown.
- Retries: Automatically retries requests that fail with a rate limit error (429) or a server error (5xx).
- Detailed Logging: Comprehensive logging for easy debugging.
This project uses commitlint to enforce conventional commit messages and
release-please to automate releases.
-
Install dependencies:
npm install
-
Make your changes.
-
Commit your changes: Your commit messages must follow the Conventional Commits format. For example:
feat: add new feature fix: correct a bug docs: update documentation -
Push your changes: When you push to
main,release-pleasewill automatically create a pull request with the next version number and release notes.
If you're having issues with anything, please open an issue on the GitHub repository.