GithubBackup/gemini-balance
1
0
Fork 0
mirror of https://github.com/snailyp/gemini-balance.git synced 2026-05-11 10:00:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: Enhance project description, add badges, and clarify licensing terms

Browse Source
This commit is contained in:
snaily
2025-07-20 16:08:52 +08:00
parent ebfa1d247c
commit 9c285e38ef
2 changed files with 385 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

391
README.md
View File

@@ -8,31 +8,33 @@
</a>
</p>
> ⚠️ This project is licensed under the CC BY-NC 4.0 (Attribution-NonCommercial) license. Any form of commercial resale service is prohibited. See the LICENSE file for details.
<p align="center">
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.9%2B-blue.svg" alt="Python"></a>
<a href="https://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.100%2B-green.svg" alt="FastAPI"></a>
<a href="https://www.uvicorn.org/"><img src="https://img.shields.io/badge/Uvicorn-running-purple.svg" alt="Uvicorn"></a>
<a href="https://t.me/+soaHax5lyI0wZDVl"><img src="https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram" alt="Telegram Group"></a>
</p>
> I have never sold this service on any platform. If you encounter someone selling this service, they are definitely a reseller. Please be careful not to be deceived.
> ⚠️ **Important**: This project is licensed under the [CC BY-NC 4.0](LICENSE) 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.
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-green.svg)](https://fastapi.tiangolo.com/)
[![Uvicorn](https://img.shields.io/badge/Uvicorn-running-purple.svg)](https://www.uvicorn.org/)
[![Telegram Group](https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram)](https://t.me/+soaHax5lyI0wZDVl)
---
> Telegram Group: <https://t.me/+soaHax5lyI0wZDVl>
## 📖 Project Introduction
## 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.
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.
**Project Structure:**
<details>
<summary>📂 View Project Structure</summary>
```plaintext
app/
├── config/ # Configuration management
├── core/ # Core application logic (FastAPI instance creation, middleware, etc.)
├── database/ # Database models and connections
├── domain/ # Business domain objects (optional)
├── domain/ # Business domain objects
├── exception/ # Custom exceptions
├── handler/ # Request handlers (optional, or handled in router)
├── handler/ # Request handlers
├── log/ # Logging configuration
├── main.py # Application entry point
├── middleware/ # FastAPI middleware
@@ -41,250 +43,227 @@ app/
├── 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
└── utils/ # Utility functions
```
</details>
---
## ✨ Feature Highlights
* **Multi-Key Load Balancing**: Supports configuring multiple Gemini API Keys (`API_KEYS`) for automatic sequential polling, improving availability and concurrency.
* **Visual Configuration Takes Effect Immediately**: Configurations modified through the admin backend take effect without restarting the service. Remember to click save for changes to apply.
* **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.
![Configuration Panel](files/image4.png)
* **Dual Protocol API Compatibility**: Supports forwarding CHAT API requests in both Gemini and OpenAI formats.
```plaintext
openai baseurl `http://localhost:8000(/hf)/v1`
gemini baseurl `http://localhost:8000(/gemini)/v1beta`
```
* **Supports Image-Text Chat and Image Modification**: `IMAGE_MODELS` configures which models can perform image-text chat and image editing. When actually calling, use the `configured_model-image` model name to use this feature.
* **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.
![Chat with Image Generation](files/image6.png)
![Modify Image](files/image7.png)
* **Supports Web Search**: Supports web search. `SEARCH_MODELS` configures which models can perform web searches. When actually calling, use the `configured_model-search` model name to use this feature.
* **Web Search**: Configure models with `SEARCH_MODELS` to support web search. Use the `configured_model-search` model name to invoke.
![Web Search](files/image8.png)
* **Key Status Monitoring**: Provides a `/keys_status` page (requires authentication) to view the status and usage of each Key in real-time.
* **Key Status Monitoring**: Provides a `/keys_status` page (authentication required) for real-time monitoring.
![Monitoring Panel](files/image.png)
* **Detailed Logging**: Provides detailed error logs for easy troubleshooting.
* **Detailed Logging**: Provides detailed error logs for easy troubleshooting.
![Call Details](files/image1.png)
![Log List](files/image2.png)
![Log Details](files/image3.png)
* **Support for Custom Gemini Proxy**: Supports custom Gemini proxies, such as those built on Deno or Cloudflare.
* **OpenAI Image Generation API Compatibility**: Adapts the `imagen-3.0-generate-002` model interface to be compatible with the OpenAI image generation API, supporting client calls.
* **Flexible Key Addition**: Flexible way to add keys using regex matching for `gemini_key`, with key deduplication.
* **Flexible Key Addition**: Add keys in batches using the `gemini_key` regex, with automatic deduplication.
![Add Key](files/image5.png)
* **OpenAI Format Embeddings API Compatibility**: Perfectly adapts to the OpenAI format `embeddings` interface, usable for local document vectorization.
* **Streamlined Response Optimization**: Optional stream output optimizer (`STREAM_OPTIMIZER_ENABLED`) to improve the experience of long-text stream responses.
* **Failure Retry and Key Management**: Automatically handles API request failures, retries (`MAX_RETRIES`), automatically disables Keys after too many failures (`MAX_FAILURES`), and periodically checks for recovery (`CHECK_INTERVAL_HOURS`).
* **Docker Support**: Supports AMD and ARM architecture Docker deployments. You can also build your own Docker image.
> Image address: docker pull ghcr.io/snailyp/gemini-balance:latest
* **Automatic Model List Maintenance**: Supports fetching OpenAI and Gemini model lists, perfectly compatible with NewAPI's automatic model list fetching, no manual entry required.
* **Support for Removing Unused Models**: Too many default models are provided, many of which are not used. You can filter them out using `FILTERED_MODELS`.
* **Proxy Support**: Supports configuring HTTP/SOCKS5 proxy servers (`PROXIES`) for accessing the Gemini API, convenient for use in special network environments. Supports batch adding proxies.
* **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
### Build Docker Yourself (Recommended)
#### a) Build with Dockerfile
1. **Build Image**:
### 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:
```bash
docker build -t gemini-balance .
docker-compose up -d
```
2. **Run Container**:
```bash
docker run -d -p 8000:8000 --env-file .env gemini-balance
```
* `-d`: Run in detached mode.
* `-p 8000:8000`: Map port 8000 of the container to port 8000 of the host.
* `--env-file .env`: Use the `.env` file to set environment variables.
> Note: If using an SQLite database, you need to mount a data volume to persist
>
> ```bash
> docker run -d -p 8000:8000 --env-file .env -v /path/to/data:/app/data gemini-balance
> ```
>
> Where `/path/to/data` is the data storage path on the host, and `/app/data` is the data directory inside the container.
#### b) Deploy with an Existing Docker Image
1. **Pull Image**:
### Option 2: Docker Command
1. **Pull Image**:
```bash
docker pull ghcr.io/snailyp/gemini-balance:latest
```
2. **Run Container**:
2. **Prepare `.env` file**:
Copy `.env.example` to `.env` and configure it.
3. **Run Container**:
```bash
docker run -d -p 8000:8000 --env-file .env ghcr.io/snailyp/gemini-balance:latest
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.
* `-d`: Run in detached mode.
* `-p 8000:8000`: Map port 8000 of the container to port 8000 of the host (adjust as needed).
* `--env-file .env`: Use the `.env` file to set environment variables (ensure the `.env` file exists in the directory where the command is executed).
> Note: If using an SQLite database, you need to mount a data volume to persist
>
> ```bash
> docker run -d -p 8000:8000 --env-file .env -v /path/to/data:/app/data ghcr.io/snailyp/gemini-balance:latest
> ```
>
> Where `/path/to/data` is the data storage path on the host, and `/app/data` is the data directory inside the container.
### Run Locally (Suitable for Development and Testing)
If you want to run the source code directly locally for development or testing, follow these steps:
1. **Ensure Prerequisites are Met**:
* Clone the repository locally.
* Install Python 3.9 or higher.
* Create and configure the `.env` file in the project root directory (refer to the "Configure Environment Variables" section above).
* Install project dependencies:
```bash
pip install -r requirements.txt
```
2. **Start Application**:
Run the following command in the project root directory:
### Option 3: Local Development
1. **Clone and Install**:
```bash
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**:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
Access the application at `http://localhost:8000`.
* `app.main:app`: Specifies the location of the FastAPI application instance (the `app` object in the `main.py` file within the `app` module).
* `--host 0.0.0.0`: Makes the application accessible from any IP address on the local network.
* `--port 8000`: Specifies the port number the application listens on (you can change this as needed).
* `--reload`: Enables automatic reloading. When you modify the code, the service will automatically restart, which is very suitable for development environments (remove this option in production environments).
3. **Access Application**:
After the application starts, you can access `http://localhost:8000` (or the host and port you specified) through a browser or API tool.
### Complete Configuration List
| Configuration Item | Description | Default Value |
| :----------------------------- | :-------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Database Configuration** | | |
| `DATABASE_TYPE` | Optional, database type, supports `mysql` or `sqlite` | `mysql` |
| `SQLITE_DATABASE` | Optional, required when using `sqlite`, SQLite database file path | `default_db` |
| `MYSQL_HOST` | Required when using `mysql`, MySQL database host address | `localhost` |
| `MYSQL_SOCKET` | Optional, MySQL database socket address | `/var/run/mysqld/mysqld.sock` |
| `MYSQL_PORT` | Required when using `mysql`, MySQL database port | `3306` |
| `MYSQL_USER` | Required when using `mysql`, MySQL database username | `your_db_user` |
| `MYSQL_PASSWORD` | Required when using `mysql`, MySQL database password | `your_db_password` |
| `MYSQL_DATABASE` | Required when using `mysql`, MySQL database name | `defaultdb` |
| **API Related Configuration** | | |
| `API_KEYS` | Required, list of Gemini API keys for load balancing | `["your-gemini-api-key-1", "your-gemini-api-key-2"]` |
| `ALLOWED_TOKENS` | Required, list of tokens allowed to access | `["your-access-token-1", "your-access-token-2"]` |
| `AUTH_TOKEN` | Optional, super admin token with all permissions, defaults to the first of `ALLOWED_TOKENS` if not set | `sk-123456` |
| `TEST_MODEL` | Optional, model name used to test if a key is usable | `gemini-1.5-flash` |
| `IMAGE_MODELS` | Optional, list of models that support drawing functions | `["gemini-2.0-flash-exp"]` |
| `SEARCH_MODELS` | Optional, list of models that support search functions | `["gemini-2.0-flash-exp"]` |
| `FILTERED_MODELS` | Optional, list of disabled models | `["gemini-1.0-pro-vision-latest", ...]` |
| `TOOLS_CODE_EXECUTION_ENABLED` | Optional, whether to enable the code execution tool | `false` |
| `SHOW_SEARCH_LINK` | Optional, whether to display search result links in the response | `true` |
| `SHOW_THINKING_PROCESS` | Optional, whether to display the model's thinking process | `true` |
| `THINKING_MODELS` | Optional, list of models that support thinking functions | `[]` |
| `THINKING_BUDGET_MAP` | Optional, thinking function budget mapping (model_name:budget_value) | `{}` |
| `URL_NORMALIZATION_ENABLED` | Optional, whether to enable intelligent URL routing mapping | `false` |
| `URL_CONTEXT_ENABLED` | Optional, whether to enable URL context understanding | `false` |
| `URL_CONTEXT_MODELS` | Optional, list of models that support URL context understanding | `[]` |
| `BASE_URL` | Optional, Gemini API base URL, no modification needed by default | `https://generativelanguage.googleapis.com/v1beta` |
| `MAX_FAILURES` | Optional, number of times a single key is allowed to fail | `3` |
| `MAX_RETRIES` | Optional, maximum number of retries for failed API requests | `3` |
| `CHECK_INTERVAL_HOURS` | Optional, time interval (hours) to check if a disabled Key has recovered | `1` |
| `TIMEZONE` | Optional, timezone used by the application | `Asia/Shanghai` |
| `TIME_OUT` | Optional, request timeout (seconds) | `300` |
| `PROXIES` | Optional, list of proxy servers (e.g., `http://user:pass@host:port`, `socks5://host:port`) | `[]` |
| `LOG_LEVEL` | Optional, log level, e.g., DEBUG, INFO, WARNING, ERROR, CRITICAL | `INFO` |
| `AUTO_DELETE_ERROR_LOGS_ENABLED` | Optional, whether to enable automatic deletion of error logs | `true` |
| `AUTO_DELETE_ERROR_LOGS_DAYS` | Optional, automatically delete error logs older than this many days (e.g., 1, 7, 30) | `7` |
| `AUTO_DELETE_REQUEST_LOGS_ENABLED`| Optional, whether to enable automatic deletion of request logs | `false` |
| `AUTO_DELETE_REQUEST_LOGS_DAYS` | Optional, automatically delete request logs older than this many days (e.g., 1, 7, 30) | `30` |
| `SAFETY_SETTINGS` | Optional, safety settings (JSON string format), used to configure content safety thresholds. Example values may need adjustment based on actual model support. | `[{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "OFF"}, {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_CIVIC_INTEGRITY", "threshold": "BLOCK_NONE"}]` |
| **TTS Related** | | |
| `TTS_MODEL` | Optional, TTS model name | `gemini-2.5-flash-preview-tts` |
| `TTS_VOICE_NAME` | Optional, TTS voice name | `Zephyr` |
| `TTS_SPEED` | Optional, TTS speed | `normal` |
| **Image Generation Related** | | |
| `PAID_KEY` | Optional, paid API Key for advanced features like image generation | `your-paid-api-key` |
| `CREATE_IMAGE_MODEL` | Optional, image generation model | `imagen-3.0-generate-002` |
| `UPLOAD_PROVIDER` | Optional, image upload provider: `smms`, `picgo`, `cloudflare_imgbed` | `smms` |
| `SMMS_SECRET_TOKEN` | Optional, API Token for SM.MS image hosting | `your-smms-token` |
| `PICGO_API_KEY` | Optional, API Key for [PicoGo](https://www.picgo.net/) image hosting | `your-picogo-apikey` |
| `CLOUDFLARE_IMGBED_URL` | Optional, [CloudFlare](https://github.com/MarSeventh/CloudFlare-ImgBed) image hosting upload address | `https://xxxxxxx.pages.dev/upload` |
| `CLOUDFLARE_IMGBED_AUTH_CODE` | Optional, authentication key for CloudFlare image hosting | `your-cloudflare-imgber-auth-code` |
| `CLOUDFLARE_IMGBED_UPLOAD_FOLDER` | Optional, upload folder path for CloudFlare image hosting | `""` |
| **Stream Optimizer Related** | | |
| `STREAM_OPTIMIZER_ENABLED` | Optional, whether to enable stream output optimization | `false` |
| `STREAM_MIN_DELAY` | Optional, minimum delay for stream output | `0.016` |
| `STREAM_MAX_DELAY` | Optional, maximum delay for stream output | `0.024` |
| `STREAM_SHORT_TEXT_THRESHOLD` | Optional, short text threshold | `10` |
| `STREAM_LONG_TEXT_THRESHOLD` | Optional, long text threshold | `50` |
| `STREAM_CHUNK_SIZE` | Optional, stream output chunk size | `5` |
| **Fake Stream Related** | | |
| `FAKE_STREAM_ENABLED` | Optional, whether to enable fake streaming for models or scenarios that don't support streaming | `false` |
| `FAKE_STREAM_EMPTY_DATA_INTERVAL_SECONDS` | Optional, interval in seconds for sending heartbeat empty data during fake streaming | `5` |
---
## ⚙️ API Endpoints
The following are the main API endpoints provided by the service:
### Gemini API Format (`/gemini/v1beta`)
### Gemini API Related (`(/gemini)/v1beta`)
* `GET /models`: List available Gemini models.
* `POST /models/{model_name}:generateContent`: Generate content.
* `POST /models/{model_name}:streamGenerateContent`: Stream content generation.
* `GET /models`: List available Gemini models.
* `POST /models/{model_name}:generateContent`: Generate content using the specified Gemini model.
* `POST /models/{model_name}:streamGenerateContent`: Stream content generation using the specified Gemini model.
### OpenAI API Format
### OpenAI API Related
#### Hugging Face (HF) Compatible
* `GET (/hf)/v1/models`: List available models (uses Gemini format underneath).
* `POST (/hf)/v1/chat/completions`: Perform chat completion (uses Gemini format underneath, supports streaming).
* `POST (/hf)/v1/embeddings`: Create text embeddings (uses Gemini format underneath).
* `POST (/hf)/v1/images/generations`: Generate images (uses Gemini format underneath).
* `GET /openai/v1/models`: List available models (uses OpenAI format underneath).
* `POST /openai/v1/chat/completions`: Perform chat completion (uses OpenAI format underneath, supports streaming, can prevent truncation, and is faster).
* `POST /openai/v1/embeddings`: Create text embeddings (uses OpenAI format underneath).
* `POST /openai/v1/images/generations`: Generate images (uses OpenAI format underneath).
* `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
* `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.
---
<details>
<summary>📋 View Full Configuration List</summary>
| Configuration Item | Description | Default Value |
| :--- | :--- | :--- |
| **Database** | | |
| `DATABASE_TYPE` | `mysql` or `sqlite` | `mysql` |
| `SQLITE_DATABASE` | Path for SQLite database file | `default_db` |
| `MYSQL_HOST` | MySQL host address | `localhost` |
| `MYSQL_SOCKET` | MySQL socket address | `/var/run/mysqld/mysqld.sock` |
| `MYSQL_PORT` | MySQL port | `3306` |
| `MYSQL_USER` | MySQL username | `your_db_user` |
| `MYSQL_PASSWORD` | MySQL password | `your_db_password` |
| `MYSQL_DATABASE` | MySQL database name | `defaultdb` |
| **API** | | |
| `API_KEYS` | **Required**, list of Gemini API keys | `[]` |
| `ALLOWED_TOKENS` | **Required**, list of access tokens | `[]` |
| `AUTH_TOKEN` | Super admin token, defaults to the first of `ALLOWED_TOKENS` | `sk-123456` |
| `TEST_MODEL` | Model for testing key validity | `gemini-1.5-flash` |
| `IMAGE_MODELS` | Models supporting image generation | `["gemini-2.0-flash-exp"]` |
| `SEARCH_MODELS` | Models supporting web search | `["gemini-2.0-flash-exp"]` |
| `FILTERED_MODELS` | Disabled models | `[]` |
| `TOOLS_CODE_EXECUTION_ENABLED` | Enable code execution tool | `false` |
| `SHOW_SEARCH_LINK` | Display search result links in response | `true` |
| `SHOW_THINKING_PROCESS` | Display model's thinking process | `true` |
| `THINKING_MODELS` | Models supporting thinking process | `[]` |
| `THINKING_BUDGET_MAP` | Budget map for thinking function (model:budget) | `{}` |
| `URL_NORMALIZATION_ENABLED` | Enable smart URL routing | `false` |
| `URL_CONTEXT_ENABLED` | Enable URL context understanding | `false` |
| `URL_CONTEXT_MODELS` | Models supporting URL context | `[]` |
| `BASE_URL` | Gemini API base URL | `https://generativelanguage.googleapis.com/v1beta` |
| `MAX_FAILURES` | Max failures allowed per key | `3` |
| `MAX_RETRIES` | Max retries for failed API requests | `3` |
| `CHECK_INTERVAL_HOURS` | Interval (hours) to re-check disabled keys | `1` |
| `TIMEZONE` | Application timezone | `Asia/Shanghai` |
| `TIME_OUT` | Request timeout (seconds) | `300` |
| `PROXIES` | List of proxy servers | `[]` |
| **Logging & Security** | | |
| `LOG_LEVEL` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |
| `AUTO_DELETE_ERROR_LOGS_ENABLED` | Auto-delete error logs | `true` |
| `AUTO_DELETE_ERROR_LOGS_DAYS` | Error log retention period (days) | `7` |
| `AUTO_DELETE_REQUEST_LOGS_ENABLED`| Auto-delete request logs | `false` |
| `AUTO_DELETE_REQUEST_LOGS_DAYS` | Request log retention period (days) | `30` |
| `SAFETY_SETTINGS` | Content safety thresholds (JSON string) | `[{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}, ...]` |
| **TTS** | | |
| `TTS_MODEL` | TTS model name | `gemini-2.5-flash-preview-tts` |
| `TTS_VOICE_NAME` | TTS voice name | `Zephyr` |
| `TTS_SPEED` | TTS speed | `normal` |
| **Image Generation** | | |
| `PAID_KEY` | Paid API Key for advanced features | `your-paid-api-key` |
| `CREATE_IMAGE_MODEL` | Image generation model | `imagen-3.0-generate-002` |
| `UPLOAD_PROVIDER` | Image upload provider: `smms`, `picgo`, `cloudflare_imgbed` | `smms` |
| `SMMS_SECRET_TOKEN` | SM.MS API Token | `your-smms-token` |
| `PICGO_API_KEY` | PicoGo API Key | `your-picogo-apikey` |
| `CLOUDFLARE_IMGBED_URL` | CloudFlare ImgBed upload URL | `https://xxxxxxx.pages.dev/upload` |
| `CLOUDFLARE_IMGBED_AUTH_CODE`| CloudFlare ImgBed auth key | `your-cloudflare-imgber-auth-code` |
| `CLOUDFLARE_IMGBED_UPLOAD_FOLDER`| CloudFlare ImgBed upload folder | `""` |
| **Stream Optimizer** | | |
| `STREAM_OPTIMIZER_ENABLED` | Enable stream output optimization | `false` |
| `STREAM_MIN_DELAY` | Minimum stream output delay | `0.016` |
| `STREAM_MAX_DELAY` | Maximum stream output delay | `0.024` |
| `STREAM_SHORT_TEXT_THRESHOLD`| Short text threshold | `10` |
| `STREAM_LONG_TEXT_THRESHOLD` | Long text threshold | `50` |
| `STREAM_CHUNK_SIZE` | Stream output chunk size | `5` |
| **Fake Stream** | | |
| `FAKE_STREAM_ENABLED` | Enable fake streaming | `false` |
| `FAKE_STREAM_EMPTY_DATA_INTERVAL_SECONDS` | Heartbeat interval for fake streaming (seconds) | `5` |
</details>
---
## 🤝 Contributing
Pull Requests or Issues are welcome.
## 🎉 Special Thanks
Special thanks to the following projects and platforms for providing image hosting services for this project:
* [PicGo](https://www.picgo.net/)
* [SM.MS](https://smms.app/)
* [CloudFlare-ImgBed](https://github.com/MarSeventh/CloudFlare-ImgBed) open source project
## 🙏 Thanks to Contributors
Thanks to all developers who contributed to this project!
[![Contributors](https://contrib.rocks/image?repo=snailyp/gemini-balance)](https://github.com/snailyp/gemini-balance/graphs/contributors)
## Thanks to Our Supporters
A special shout-out to DigitalOcean for providing the rock-solid and dependable cloud infrastructure that keeps this project humming!
[![DigitalOcean Logo](files/dataocean.svg)](https://m.do.co/c/b249dd7f3b4c)
CDN acceleration and security protection for this project are sponsored by Tencent EdgeOne.
[![EdgeOne Logo](https://edgeone.ai/media/34fe3a45-492d-4ea4-ae5d-ea1087ca7b4b.png)](https://edgeone.ai/?from=github)
## ⭐ Star History
[![Star History Chart](https://api.star-history.com/svg?repos=snailyp/gemini-balance&type=Date)](https://star-history.com/#snailyp/gemini-balance&Date)
## 🎉 Special Thanks
* [PicGo](https://www.picgo.net/)
* [SM.MS](https://smms.app/)
* [CloudFlare-ImgBed](https://github.com/MarSeventh/CloudFlare-ImgBed)
## 🙏 Our Supporters
A special shout-out to [DigitalOcean](https://m.do.co/c/b249dd7f3b4c) for providing the rock-solid and dependable cloud infrastructure that keeps this project humming!
<a href="https://m.do.co/c/b249dd7f3b4c">
<img src="files/dataocean.svg" alt="DigitalOcean Logo" width="200"/>
</a>
CDN acceleration and security protection for this project are sponsored by [Tencent EdgeOne](https://edgeone.ai/?from=github).
<a href="https://edgeone.ai/?from=github">
<img src="https://edgeone.ai/media/34fe3a45-492d-4ea4-ae5d-ea1087ca7b4b.png" alt="EdgeOne Logo" width="200"/>
</a>
## 💖 Friendly Projects
* **[OneLine](https://github.com/chengtx809/OneLine)** by [chengtx809](https://github.com/chengtx809) - OneLine: AI-driven hot event timeline generation tool
* **[OneLine](https://github.com/chengtx809/OneLine)** by [chengtx809](https://github.com/chengtx809) - AI-driven hot event timeline generation tool.
## 🎁 Project Support
@@ -292,4 +271,4 @@ If you find this project helpful, consider supporting me via [Afdian](https://af
## License
This project is licensed under the CC BY-NC 4.0 (Attribution-NonCommercial) license. Any form of commercial resale service is prohibited. See the LICENSE file for details.
This project is licensed under the [CC BY-NC 4.0](LICENSE) (Attribution-NonCommercial) license.

404
README_ZH.md
View File

@@ -6,30 +6,33 @@
</a>
</p>
> ⚠️ 本项目采用 CC BY-NC 4.0（署名-非商业性使用）协议，禁止任何形式的商业倒卖服务，详见 LICENSE 文件。
<p align="center">
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.9%2B-blue.svg" alt="Python"></a>
<a href="https://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.100%2B-green.svg" alt="FastAPI"></a>
<a href="https://www.uvicorn.org/"><img src="https://img.shields.io/badge/Uvicorn-running-purple.svg" alt="Uvicorn"></a>
<a href="https://t.me/+soaHax5lyI0wZDVl"><img src="https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram" alt="Telegram Group"></a>
</p>
> 本人从未在各个平台售卖服务，如有遇到售卖此服务者，那一定是倒卖狗，大家切记不要上当受骗。
> ⚠️ **重要声明**: 本项目采用 [CC BY-NC 4.0](LICENSE) 协议，**禁止任何形式的商业倒卖服务**。
> 本人从未在任何平台售卖服务，如遇售卖，均为倒卖行为，请勿上当受骗。
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100%2B-green.svg)](https://fastapi.tiangolo.com/)
[![Uvicorn](https://img.shields.io/badge/Uvicorn-running-purple.svg)](https://www.uvicorn.org/)
[![Telegram Group](https://img.shields.io/badge/Telegram-Group-blue.svg?logo=telegram)](https://t.me/+soaHax5lyI0wZDVl)
> 交流群：https://t.me/+soaHax5lyI0wZDVl
---
## 项目简介
## 📖 项目简介
Gemini Balance 是一个基于 Python FastAPI 构建的应用程序，旨在提供 Google Gemini API 的代理和负载均衡功能。它允许您管理多个 Gemini API Key，并通过简单的配置实现 Key 的轮询、认证、模型过滤和状态监控。此外，项目还集成了图像生成和多种图床上传功能，并支持 OpenAI API 格式的代理。
**Gemini Balance** 是一个基于 Python FastAPI 构建的应用程序，旨在提供 Google Gemini API 的代理和负载均衡功能。它允许您管理多个 Gemini API Key，并通过简单的配置实现 Key 的轮询、认证、模型过滤和状态监控。此外，项目还集成了图像生成和多种图床上传功能，并支持 OpenAI API 格式的代理。
**项目结构:**
<details>
<summary>📂 查看项目结构</summary>
```plaintext
app/
├── config/ # 配置管理
├── core/ # 核心应用逻辑 (FastAPI 实例创建, 中间件等)
├── database/ # 数据库模型和连接
├── domain/ # 业务领域对象 (可选)
├── domain/ # 业务领域对象
├── exception/ # 自定义异常
├── handler/ # 请求处理器 (可选, 或在 router 中处理)
├── handler/ # 请求处理器
├── log/ # 日志配置
├── main.py # 应用入口
├── middleware/ # FastAPI 中间件
@@ -38,228 +41,200 @@ app/
├── service/ # 业务逻辑服务 (聊天, Key 管理, 统计等)
├── static/ # 静态文件 (CSS, JS)
├── templates/ # HTML 模板 (如 Key 状态页)
├── utils/ # 工具函数
└── utils/ # 工具函数
```
</details>
---
## ✨ 功能亮点
* **多 Key 负载均衡**: 支持配置多个 Gemini API Key (`API_KEYS`)，自动按顺序轮询使用，提高可用性和并发能力。
* **可视化配置即时生效**: 通过管理后台修改配置后，无需重启服务即可生效，切记要点击保存才会生效。
![配置面板](files/image4.png)
* **双协议API 兼容**: 同时支持 Gemini 和 OpenAI 格式的 CHAT API 请求转发。
* **多 Key 负载均衡**: 支持配置多个 Gemini API Key (`API_KEYS`)，自动按顺序轮询使用，提高可用性和并发能力。
* **可视化配置即时生效**: 通过管理后台修改配置后，无需重启服务即可生效。
![配置面板](files/image4.png)
* **双协议 API 兼容**: 同时支持 Gemini 和 OpenAI 格式的 CHAT API 请求转发。
* OpenAI Base URL: `http://localhost:8000(/hf)/v1`
* Gemini Base URL: `http://localhost:8000(/gemini)/v1beta`
* **图文对话与修图**: 通过 `IMAGE_MODELS` 配置支持图文对话和修图功能的模型，调用时使用 `配置模型-image` 模型名。
![对话生图](files/image6.png)
![修改图片](files/image7.png)
* **联网搜索**: 通过 `SEARCH_MODELS` 配置支持联网搜索的模型，调用时使用 `配置模型-search` 模型名。
![联网搜索](files/image8.png)
* **Key 状态监控**: 提供 `/keys_status` 页面（需要认证），实时查看各 Key 的状态和使用情况。
![监控面板](files/image.png)
* **详细日志记录**: 提供详细的错误日志，方便排查问题。
![调用详情](files/image1.png)
![日志列表](files/image2.png)
![日志详情](files/image3.png)
* **灵活的密钥添加**: 支持通过正则表达式 `gemini_key` 批量添加密钥，并自动去重。
![添加密钥](files/image5.png)
* **失败重试与自动禁用**: 自动处理 API 请求失败，进行重试 (`MAX_RETRIES`)，并在 Key 失效次数过多时自动禁用 (`MAX_FAILURES`)，定时检查恢复 (`CHECK_INTERVAL_HOURS`)。
* **全面的 API 兼容**:
* **Embeddings 接口**: 完美适配 OpenAI 格式的 `embeddings` 接口。
* **画图接口**: 将 `imagen-3.0-generate-002` 模型接口改造为 OpenAI 画图接口格式。
* **模型列表自动维护**: 自动获取并同步 Gemini 和 OpenAI 的最新模型列表，兼容 New API。
* **代理支持**: 支持配置 HTTP/SOCKS5 代理 (`PROXIES`)，方便在特殊网络环境下使用。
* **Docker 支持**: 提供 AMD 和 ARM 架构的 Docker 镜像，方便快速部署。
* 镜像地址: `ghcr.io/snailyp/gemini-balance:latest`
```palintext
openai baseurl `http://localhost:8000(/hf)/v1`
gemini baseurl `http://localhost:8000(/gemini)/v1beta`
```
* **支持图文对话和修改图片**: `IMAGE_MODELS`配置哪个模型可以图文对话和修图的功能，实际调用的时候，用 `配置模型-image`这个模型名对话使用该功能。
![对话生图](files/image6.png)
![修改图片](files/image7.png)
* **支持联网搜索**: 支持联网搜索，`SEARCH_MODELS`配置哪些模型可以联网搜索，实际调用的时候，用 `配置模型-search`这个模型名对话使用该功能
![联网搜索](files/image8.png)
* **Key 状态监控**: 提供 `/keys_status` 页面（需要认证），实时查看各 Key 的状态和使用情况。
![监控面板](files/image.png)
* **详细的日志记录**: 提供详细的错误日志，方便排查。
![调用详情](files/image1.png)
![日志列表](files/image2.png)
![日志详情](files/image3.png)
* **支持自定义gemini代理**: 支持自定义gemini代理，比如自行在deno或者cloudflare上搭建gemini代理
* **openai画图接口兼容**: 将`imagen-3.0-generate-002`模型接口改造成openai画图接口，支持客户端调用。
* **灵活的添加密钥方式**: 灵活的添加密钥方式，采用正则匹配`gemini_key`,密钥去重
![添加密钥](files/image5.png)
* **兼容openai格式embeddings接口**：完美适配openai格式的`embeddings`接口，可用于本地文档向量化。
* **流式响应优化**: 可选的流式输出优化器 (`STREAM_OPTIMIZER_ENABLED`)，改善长文本流式响应的体验。
* **失败重试与 Key 管理**: 自动处理 API 请求失败，进行重试 (`MAX_RETRIES`)，并在 Key 失效次数过多时自动禁用 (`MAX_FAILURES`)，定时检查恢复 (`CHECK_INTERVAL_HOURS`)。
* **Docker 支持**: 支持AMD，ARM架构的docker部署，也可自行构建docker镜像。
>镜像地址: docker pull ghcr.io/snailyp/gemini-balance:latest
* **模型列表自动维护**: 支持openai和gemini模型列表获取，与newapi自动获取模型列表完美兼容，无需手动填写。
* **支持移除不使用的模型**: 默认提供的模型太多，很多用不上，可以通过`FILTERED_MODELS`过滤掉。
* **代理支持**: 支持配置 HTTP/SOCKS5 代理服务器 (`PROXIES`)，用于访问 Gemini API，方便在特殊网络环境下使用。支持批量添加代理。
---
## 🚀 快速开始
### 自行构建 Docker (推荐)
### 方式一：使用 Docker Compose (推荐)
#### a) dockerfile构建
1. **构建镜像**:
这是最推荐的部署方式，可以一键启动应用和数据库。
1. **下载 `docker-compose.yml`**:
从项目仓库获取 `docker-compose.yml` 文件。
2. **准备 `.env` 文件**:
从 `.env.example` 复制一份并重命名为 `.env`，然后根据需求修改配置。特别注意，`DATABASE_TYPE` 应设置为 `mysql`，并填写 `MYSQL_*` 相关配置。
3. **启动服务**:
在 `docker-compose.yml` 和 `.env` 文件所在的目录下，运行以下命令：
```bash
docker build -t gemini-balance .
docker-compose up -d
```
该命令会以后台模式启动 `gemini-balance` 应用和 `mysql` 数据库。
2. **运行容器**:
### 方式二：使用 Docker 命令
1. **拉取镜像**:
```bash
docker run -d -p 8000:8000 --env-file .env gemini-balance
docker pull ghcr.io/snailyp/gemini-balance:latest
```
2. **准备 `.env` 文件**:
从 `.env.example` 复制一份并重命名为 `.env`，然后根据需求修改配置。
3. **运行容器**:
```bash
docker run -d -p 8000:8000 --name gemini-balance \
-v ./data:/app/data \
--env-file .env \
ghcr.io/snailyp/gemini-balance:latest
```
* `-d`: 后台运行。
* `-p 8000:8000`: 将容器的 8000 端口映射到主机。
* `-v ./data:/app/data`: 挂载数据卷以持久化 SQLite 数据和日志。
* `--env-file .env`: 加载环境变量配置文件。
* `-d`: 后台运行。
* `-p 8000:8000`: 将容器的 8000 端口映射到主机的 8000 端口。
* `--env-file .env`: 使用 `.env` 文件设置环境变量。
> 注意：如果使用 SQLite 数据库，需要挂载数据卷以持久化数据：
> ```bash
> docker run -d -p 8000:8000 --env-file .env -v /path/to/data:/app/data gemini-balance
> ```
> 其中 `/path/to/data` 是主机上的数据存储路径，`/app/data` 是容器内的数据目录。
#### b) 用现有的docker镜像部署
1. **拉取镜像**:
```bash
docker pull ghcr.io/snailyp/gemini-balance:latest
```
2. **运行容器**:
```bash
docker run -d -p 8000:8000 --env-file .env ghcr.io/snailyp/gemini-balance:latest
```
* `-d`: 后台运行。
* `-p 8000:8000`: 将容器的 8000 端口映射到主机的 8000 端口 (根据需要调整)。
* `--env-file .env`: 使用 `.env` 文件设置环境变量 (确保 `.env` 文件存在于执行命令的目录)。
> 注意：如果使用 SQLite 数据库，需要挂载数据卷以持久化数据：
> ```bash
> docker run -d -p 8000:8000 --env-file .env -v /path/to/data:/app/data ghcr.io/snailyp/gemini-balance:latest
> ```
> 其中 `/path/to/data` 是主机上的数据存储路径，`/app/data` 是容器内的数据目录。
### 本地运行 (适用于开发和测试)
如果您想在本地直接运行源代码进行开发或测试，请按照以下步骤操作：
1. **确保已完成准备工作**:
* 克隆仓库到本地。
* 安装 Python 3.9 或更高版本。
* 在项目根目录下创建并配置好 `.env` 文件 (参考前面的"配置环境变量"部分)。
* 安装项目依赖：
```bash
pip install -r requirements.txt
```
2. **启动应用**:
在项目根目录下运行以下命令：
### 方式三：本地运行 (适用于开发)
1. **克隆仓库并安装依赖**:
```bash
git clone https://github.com/snailyp/gemini-balance.git
cd gemini-balance
pip install -r requirements.txt
```
2. **配置环境变量**:
从 `.env.example` 复制一份并重命名为 `.env`，然后根据需求修改配置。
3. **启动应用**:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
应用启动后，访问 `http://localhost:8000`。
* `app.main:app`: 指定 FastAPI 应用实例的位置 (`app` 模块中的 `main.py` 文件里的 `app` 对象)。
* `--host 0.0.0.0`: 使应用可以从本地网络中的任何 IP 地址访问。
* `--port 8000`: 指定应用监听的端口号 (您可以根据需要修改)。
* `--reload`: 启用自动重载功能。当您修改代码时，服务会自动重启，非常适合开发环境 (生产环境请移除此选项)。
3. **访问应用**:
应用启动后，您可以通过浏览器或 API 工具访问 `http://localhost:8000` (或您指定的主机和端口)。
### 完整配置项列表
| 配置项 | 说明 | 默认值 |
| :--------------------------- | :------------------------------------------------------- | :---------------------------------------------------- |
| **数据库配置** | | |
| `DATABASE_TYPE` | 可选，数据库类型，支持 `mysql` 或 `sqlite` | `mysql` |
| `SQLITE_DATABASE` | 可选，当使用 `sqlite` 时必填，SQLite 数据库文件路径 | `default_db` |
| `MYSQL_HOST` | 当使用 `mysql` 时必填，MySQL 数据库主机地址 | `localhost` |
| `MYSQL_SOCKET` | 可选，MySQL 数据库 socket 地址 | `/var/run/mysqld/mysqld.sock` |
| `MYSQL_PORT` | 当使用 `mysql` 时必填，MySQL 数据库端口 | `3306` |
| `MYSQL_USER` | 当使用 `mysql` 时必填，MySQL 数据库用户名 | `your_db_user` |
| `MYSQL_PASSWORD` | 当使用 `mysql` 时必填，MySQL 数据库密码 | `your_db_password` |
| `MYSQL_DATABASE` | 当使用 `mysql` 时必填，MySQL 数据库名称 | `defaultdb` |
| **API 相关配置** | | |
| `API_KEYS` | 必填，Gemini API 密钥列表，用于负载均衡 | `["your-gemini-api-key-1", "your-gemini-api-key-2"]` |
| `ALLOWED_TOKENS` | 必填，允许访问的 Token 列表 | `["your-access-token-1", "your-access-token-2"]` |
| `AUTH_TOKEN` | 可选，超级管理员token，具有所有权限，不填默认使用 ALLOWED_TOKENS 的第一个 | `sk-123456` |
| `TEST_MODEL` | 可选，用于测试密钥是否可用的模型名 | `gemini-1.5-flash` |
| `IMAGE_MODELS` | 可选，支持绘图功能的模型列表 | `["gemini-2.0-flash-exp"]` |
| `SEARCH_MODELS` | 可选，支持搜索功能的模型列表 | `["gemini-2.0-flash-exp"]` |
| `FILTERED_MODELS` | 可选，被禁用的模型列表 | `["gemini-1.0-pro-vision-latest", ...]` |
| `TOOLS_CODE_EXECUTION_ENABLED` | 可选，是否启用代码执行工具 | `false` |
| `SHOW_SEARCH_LINK` | 可选，是否在响应中显示搜索结果链接 | `true` |
| `SHOW_THINKING_PROCESS` | 可选，是否显示模型思考过程 | `true` |
| `THINKING_MODELS` | 可选，支持思考功能的模型列表 | `[]` |
| `THINKING_BUDGET_MAP` | 可选，思考功能预算映射 (模型名:预算值) | `{}` |
| `URL_NORMALIZATION_ENABLED` | 可选，是否启用智能路由映射功能 | `false` |
| `URL_CONTEXT_ENABLED` | 可选，是否启用URL上下文理解功能 | `false` |
| `URL_CONTEXT_MODELS` | 可选，支持URL上下文理解功能的模型列表 | `[]` |
| `BASE_URL` | 可选，Gemini API 基础 URL，默认无需修改 | `https://generativelanguage.googleapis.com/v1beta` |
| `MAX_FAILURES` | 可选，允许单个key失败的次数 | `3` |
| `MAX_RETRIES` | 可选，API 请求失败时的最大重试次数 | `3` |
| `CHECK_INTERVAL_HOURS` | 可选，检查禁用 Key 是否恢复的时间间隔 (小时) | `1` |
| `TIMEZONE` | 可选，应用程序使用的时区 | `Asia/Shanghai` |
| `TIME_OUT` | 可选，请求超时时间 (秒) | `300` |
| `PROXIES` | 可选，代理服务器列表 (例如 `http://user:pass@host:port`, `socks5://host:port`) | `[]` |
| `LOG_LEVEL` | 可选，日志级别，例如 DEBUG, INFO, WARNING, ERROR, CRITICAL | `INFO` |
| `AUTO_DELETE_ERROR_LOGS_ENABLED` | 可选，是否开启自动删除错误日志 | `true` |
| `AUTO_DELETE_ERROR_LOGS_DAYS` | 可选，自动删除多少天前的错误日志 (例如 1, 7, 30) | `7` |
| `AUTO_DELETE_REQUEST_LOGS_ENABLED`| 可选，是否开启自动删除请求日志 | `false` |
| `AUTO_DELETE_REQUEST_LOGS_DAYS` | 可选，自动删除多少天前的请求日志 (例如 1, 7, 30) | `30` |
| `SAFETY_SETTINGS` | 可选，安全设置 (JSON 字符串格式)，用于配置内容安全阈值。示例值可能需要根据实际模型支持情况调整。 | `[{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "OFF"}, {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "OFF"}, {"category": "HARM_CATEGORY_CIVIC_INTEGRITY", "threshold": "BLOCK_NONE"}]` |
| **TTS 相关** | | |
| `TTS_MODEL` | 可选，TTS 模型名称 | `gemini-2.5-flash-preview-tts` |
| `TTS_VOICE_NAME` | 可选，TTS 语音名称 | `Zephyr` |
| `TTS_SPEED` | 可选，TTS 语速 | `normal` |
| **图像生成相关** | | |
| `PAID_KEY` | 可选，付费版API Key，用于图片生成等高级功能 | `your-paid-api-key` |
| `CREATE_IMAGE_MODEL` | 可选，图片生成模型 | `imagen-3.0-generate-002` |
| `UPLOAD_PROVIDER` | 可选，图片上传提供商: `smms`, `picgo`, `cloudflare_imgbed` | `smms` |
| `SMMS_SECRET_TOKEN` | 可选，SM.MS图床的API Token | `your-smms-token` |
| `PICGO_API_KEY` | 可选，[PicoGo](https://www.picgo.net/)图床的API Key | `your-picogo-apikey` |
| `CLOUDFLARE_IMGBED_URL` | 可选，[CloudFlare](https://github.com/MarSeventh/CloudFlare-ImgBed) 图床上传地址 | `https://xxxxxxx.pages.dev/upload` |
| `CLOUDFLARE_IMGBED_AUTH_CODE`| 可选，CloudFlare图床的鉴权key | `your-cloudflare-imgber-auth-code` |
| `CLOUDFLARE_IMGBED_UPLOAD_FOLDER`| 可选，CloudFlare图床的上传文件夹路径 | `""` |
| **流式优化器相关** | | |
| `STREAM_OPTIMIZER_ENABLED` | 可选，是否启用流式输出优化 | `false` |
| `STREAM_MIN_DELAY` | 可选，流式输出最小延迟 | `0.016` |
| `STREAM_MAX_DELAY` | 可选，流式输出最大延迟 | `0.024` |
| `STREAM_SHORT_TEXT_THRESHOLD`| 可选，短文本阈值 | `10` |
| `STREAM_LONG_TEXT_THRESHOLD` | 可选，长文本阈值 | `50` |
| `STREAM_CHUNK_SIZE` | 可选，流式输出块大小 | `5` |
| **伪流式 (Fake Stream) 相关** | | |
| `FAKE_STREAM_ENABLED` | 可选，是否启用伪流式传输，用于不支持流式的模型或场景 | `false` |
| `FAKE_STREAM_EMPTY_DATA_INTERVAL_SECONDS` | 可选，伪流式传输时发送心跳空数据的间隔秒数 | `5` |
---
## ⚙️ API 端点
以下是服务提供的主要 API 端点：
### Gemini API 格式 (`/gemini/v1beta`)
### Gemini API 相关 (`(/gemini)/v1beta`)
* `GET /models`: 列出可用的 Gemini 模型。
* `POST /models/{model_name}:generateContent`: 生成内容。
* `POST /models/{model_name}:streamGenerateContent`: 流式生成内容。
* `GET /models`: 列出可用的 Gemini 模型。
* `POST /models/{model_name}:generateContent`: 使用指定的 Gemini 模型生成内容。
* `POST /models/{model_name}:streamGenerateContent`: 使用指定的 Gemini 模型流式生成内容。
### OpenAI API 格式
### OpenAI API 相关
#### 兼容 huggingface (HF) 格式
* `GET (/hf)/v1/models`: 列出可用的模型 (底层用的gemini格式)。
* `POST (/hf)/v1/chat/completions`: 进行聊天补全 (底层用的gemini格式, 支持流式传输)。
* `POST (/hf)/v1/embeddings`: 创建文本嵌入 (底层用的gemini格式)。
* `POST (/hf)/v1/images/generations`: 生成图像 (底层用的gemini格式)。
* `GET /openai/v1/models`: 列出可用的模型 (底层用的openai格式)。
* `POST /openai/v1/chat/completions`: 进行聊天补全 (底层用的openai格式, 支持流式传输, 可防止截断，速度也快)。
* `POST /openai/v1/embeddings`: 创建文本嵌入 (底层用的openai格式)。
* `POST /openai/v1/images/generations`: 生成图像 (底层用的openai格式)。
* `GET /hf/v1/models`: 列出模型。
* `POST /hf/v1/chat/completions`: 聊天补全。
* `POST /hf/v1/embeddings`: 创建文本嵌入。
* `POST /hf/v1/images/generations`: 生成图像。
#### 标准 OpenAI 格式
* `GET /openai/v1/models`: 列出模型。
* `POST /openai/v1/chat/completions`: 聊天补全 (推荐，速度更快，防截断)。
* `POST /openai/v1/embeddings`: 创建文本嵌入。
* `POST /openai/v1/images/generations`: 生成图像。
---
<details>
<summary>📋 查看完整配置项列表</summary>
| 配置项 | 说明 | 默认值 |
| :--- | :--- | :--- |
| **数据库配置** | | |
| `DATABASE_TYPE` | 数据库类型: `mysql` 或 `sqlite` | `mysql` |
| `SQLITE_DATABASE` | 当使用 `sqlite` 时必填，SQLite 数据库文件路径 | `default_db` |
| `MYSQL_HOST` | 当使用 `mysql` 时必填，MySQL 数据库主机地址 | `localhost` |
| `MYSQL_SOCKET` | 可选，MySQL 数据库 socket 地址 | `/var/run/mysqld/mysqld.sock` |
| `MYSQL_PORT` | 当使用 `mysql` 时必填，MySQL 数据库端口 | `3306` |
| `MYSQL_USER` | 当使用 `mysql` 时必填，MySQL 数据库用户名 | `your_db_user` |
| `MYSQL_PASSWORD` | 当使用 `mysql` 时必填，MySQL 数据库密码 | `your_db_password` |
| `MYSQL_DATABASE` | 当使用 `mysql` 时必填，MySQL 数据库名称 | `defaultdb` |
| **API 相关配置** | | |
| `API_KEYS` | **必填**, Gemini API 密钥列表，用于负载均衡 | `[]` |
| `ALLOWED_TOKENS` | **必填**, 允许访问的 Token 列表 | `[]` |
| `AUTH_TOKEN` | 超级管理员 Token，不填则使用 `ALLOWED_TOKENS` 的第一个 | `sk-123456` |
| `TEST_MODEL` | 用于测试密钥可用性的模型 | `gemini-1.5-flash` |
| `IMAGE_MODELS` | 支持绘图功能的模型列表 | `["gemini-2.0-flash-exp"]` |
| `SEARCH_MODELS` | 支持搜索功能的模型列表 | `["gemini-2.0-flash-exp"]` |
| `FILTERED_MODELS` | 被禁用的模型列表 | `[]` |
| `TOOLS_CODE_EXECUTION_ENABLED` | 是否启用代码执行工具 | `false` |
| `SHOW_SEARCH_LINK` | 是否在响应中显示搜索结果链接 | `true` |
| `SHOW_THINKING_PROCESS` | 是否显示模型思考过程 | `true` |
| `THINKING_MODELS` | 支持思考功能的模型列表 | `[]` |
| `THINKING_BUDGET_MAP` | 思考功能预算映射 (模型名:预算值) | `{}` |
| `URL_NORMALIZATION_ENABLED` | 是否启用智能路由映射功能 | `false` |
| `URL_CONTEXT_ENABLED` | 是否启用URL上下文理解功能 | `false` |
| `URL_CONTEXT_MODELS` | 支持URL上下文理解功能的模型列表 | `[]` |
| `BASE_URL` | Gemini API 基础 URL | `https://generativelanguage.googleapis.com/v1beta` |
| `MAX_FAILURES` | 单个 Key 允许的最大失败次数 | `3` |
| `MAX_RETRIES` | API 请求失败时的最大重试次数 | `3` |
| `CHECK_INTERVAL_HOURS` | 禁用 Key 恢复检查间隔 (小时) | `1` |
| `TIMEZONE` | 应用程序使用的时区 | `Asia/Shanghai` |
| `TIME_OUT` | 请求超时时间 (秒) | `300` |
| `PROXIES` | 代理服务器列表 (例如 `http://user:pass@host:port`) | `[]` |
| **日志与安全** | | |
| `LOG_LEVEL` | 日志级别: `DEBUG`, `INFO`, `WARNING`, `ERROR` | `INFO` |
| `AUTO_DELETE_ERROR_LOGS_ENABLED` | 是否自动删除错误日志 | `true` |
| `AUTO_DELETE_ERROR_LOGS_DAYS` | 错误日志保留天数 | `7` |
| `AUTO_DELETE_REQUEST_LOGS_ENABLED`| 是否自动删除请求日志 | `false` |
| `AUTO_DELETE_REQUEST_LOGS_DAYS` | 请求日志保留天数 | `30` |
| `SAFETY_SETTINGS` | 内容安全阈值 (JSON 字符串) | `[{"category": "HARM_CATEGORY_HARASSMENT", "threshold": "OFF"}, ...]` |
| **TTS 相关** | | |
| `TTS_MODEL` | TTS 模型名称 | `gemini-2.5-flash-preview-tts` |
| `TTS_VOICE_NAME` | TTS 语音名称 | `Zephyr` |
| `TTS_SPEED` | TTS 语速 | `normal` |
| **图像生成相关** | | |
| `PAID_KEY` | 付费版API Key，用于图片生成等高级功能 | `your-paid-api-key` |
| `CREATE_IMAGE_MODEL` | 图片生成模型 | `imagen-3.0-generate-002` |
| `UPLOAD_PROVIDER` | 图片上传提供商: `smms`, `picgo`, `cloudflare_imgbed` | `smms` |
| `SMMS_SECRET_TOKEN` | SM.MS图床的API Token | `your-smms-token` |
| `PICGO_API_KEY` | [PicoGo](https://www.picgo.net/)图床的API Key | `your-picogo-apikey` |
| `CLOUDFLARE_IMGBED_URL` | [CloudFlare](https://github.com/MarSeventh/CloudFlare-ImgBed) 图床上传地址 | `https://xxxxxxx.pages.dev/upload` |
| `CLOUDFLARE_IMGBED_AUTH_CODE`| CloudFlare图床的鉴权key | `your-cloudflare-imgber-auth-code` |
| `CLOUDFLARE_IMGBED_UPLOAD_FOLDER`| CloudFlare图床的上传文件夹路径 | `""` |
| **流式优化器相关** | | |
| `STREAM_OPTIMIZER_ENABLED` | 是否启用流式输出优化 | `false` |
| `STREAM_MIN_DELAY` | 流式输出最小延迟 | `0.016` |
| `STREAM_MAX_DELAY` | 流式输出最大延迟 | `0.024` |
| `STREAM_SHORT_TEXT_THRESHOLD`| 短文本阈值 | `10` |
| `STREAM_LONG_TEXT_THRESHOLD` | 长文本阈值 | `50` |
| `STREAM_CHUNK_SIZE` | 流式输出块大小 | `5` |
| **伪流式 (Fake Stream) 相关** | | |
| `FAKE_STREAM_ENABLED` | 是否启用伪流式传输 | `false` |
| `FAKE_STREAM_EMPTY_DATA_INTERVAL_SECONDS` | 伪流式传输时发送心跳空数据的间隔秒数 | `5` |
</details>
---
## 🤝 贡献
欢迎提交 Pull Request 或 Issue。
## 🎉 特别鸣谢
特别鸣谢以下项目和平台为本项目提供图床服务:
* [PicGo](https://www.picgo.net/)
* [SM.MS](https://smms.app/)
* [CloudFlare-ImgBed](https://github.com/MarSeventh/CloudFlare-ImgBed) 开源项目
## 🙏 感谢贡献者
感谢所有为本项目做出贡献的开发者！
欢迎通过提交 Pull Request 或 Issue 来为项目做出贡献。
[![Contributors](https://contrib.rocks/image?repo=snailyp/gemini-balance)](https://github.com/snailyp/gemini-balance/graphs/contributors)
@@ -267,9 +242,15 @@ app/
[![Star History Chart](https://api.star-history.com/svg?repos=snailyp/gemini-balance&type=Date)](https://star-history.com/#snailyp/gemini-balance&Date)
## 🎉 特别鸣谢
* [PicGo](https://www.picgo.net/)
* [SM.MS](https://smms.app/)
* [CloudFlare-ImgBed](https://github.com/MarSeventh/CloudFlare-ImgBed)
## 💖 友情项目
* **[OneLine](https://github.com/chengtx809/OneLine)** by [chengtx809](https://github.com/chengtx809) - OneLine一线：AI驱动的热点事件时间轴生成工具
* **[OneLine](https://github.com/chengtx809/OneLine)** by [chengtx809](https://github.com/chengtx809) - AI 驱动的热点事件时间轴生成工具。
## 🎁 项目支持
@@ -277,4 +258,19 @@ app/
## 许可证
本项目采用 CC BY-NC 4.0（署名-非商业性使用）协议，禁止任何形式的商业倒卖服务，详见 LICENSE 文件。
本项目采用 [CC BY-NC 4.0](LICENSE)（署名-非商业性使用）协议。
## 赞助商
特别感谢 [DigitalOcean](https://m.do.co/c/b249dd7f3b4c) 为本项目提供稳定可靠的云基础设施支持。
<a href="https://m.do.co/c/b249dd7f3b4c">
<img src="files/dataocean.svg" alt="DigitalOcean Logo" width="200"/>
</a>
本项目的 CDN 加速和安全防护由 [Tencent EdgeOne](https://edgeone.ai/?from=github) 赞助。
<a href="https://edgeone.ai/?from=github">
<img src="https://edgeone.ai/media/34fe3a45-492d-4ea4-ae5d-ea1087ca7b4b.png" alt="EdgeOne Logo" width="200"/>
</a>