--- title: G_AI emoji: πŸš€ colorFrom: blue colorTo: green sdk: docker pinned: false --- # Gemini-FastAPI [![Python 3.12](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/) [![FastAPI](https://img.shields.io/badge/FastAPI-0.115+-green.svg)](https://fastapi.tiangolo.com/) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [ English | [δΈ­ζ–‡](README.zh.md) ] Web-based Gemini models wrapped into an OpenAI-compatible API. Powered by [HanaokaYuzu/Gemini-API](https://github.com/HanaokaYuzu/Gemini-API). **βœ… Call Gemini's web-based models via API without an API Key, completely free!** ## Features - **πŸ” No Google API Key Required**: Use web cookies to freely access Gemini's models via API. - **πŸ” Google Search Included**: Get up-to-date answers using web-based Gemini's search capabilities. - **πŸ’Ύ Conversation Persistence**: LMDB-based storage supporting multi-turn conversations. - **πŸ–ΌοΈ Multi-modal Support**: Support for handling text, images, and file uploads. - **βš–οΈ Multi-account Load Balancing**: Distribute requests across multiple accounts with per-account proxy settings. ## Quick Start **For Docker deployment, see the [Docker Deployment](#docker-deployment) section below.** ### Prerequisites - Python 3.12 - Google account with Gemini access on web - `secure_1psid` and `secure_1psidts` cookies from Gemini web interface ### Installation #### Using uv (Recommended) ```bash git clone https://github.com/Nativu5/Gemini-FastAPI.git cd Gemini-FastAPI uv sync ``` #### Using pip ```bash git clone https://github.com/Nativu5/Gemini-FastAPI.git cd Gemini-FastAPI pip install -e . ``` ### Configuration Edit `config/config.yaml` and provide at least one credential pair: ```yaml gemini: clients: - id: "client-a" secure_1psid: "YOUR_SECURE_1PSID_HERE" secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE" proxy: null # Optional proxy URL (null/empty keeps direct connection) ``` > [!NOTE] > For details, refer to the [Configuration](#configuration-1) section below. ### Running the Server ```bash # Using uv uv run python run.py # Using Python directly python run.py ``` The server will start on `http://localhost:8000` by default. ## Hugging Face Space (Self-use) Guide If you run this project on a **Hugging Face Space for personal use**, prefer **environment variables / Space Secrets** over committing real cookies or API keys into `config/config.yaml`. ### Recommended Setup 1. Duplicate `config/config.yaml` locally as a private working config, or create your own `config/config.example.yaml`-based config 2. Store sensitive values in **Space Secrets** 3. Keep persistent data expectations modest on free Spaces: - `data/lmdb` may be reset when the Space is rebuilt - refreshed cookies stored in cache directories should not be treated as permanent 4. Use a small number of Gemini web clients unless you really need more, to reduce cold-start and initialization time ### Recommended Space Secrets / Variables ```bash CONFIG_SERVER__API_KEY=your-api-key CONFIG_GEMINI__CLIENTS__0__ID=client-a CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID=your-secure-1psid CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS=your-secure-1psidts CONFIG_STORAGE__PATH=data/lmdb CONFIG_STORAGE__RETENTION_DAYS=7 ``` ### Operational Notes for Free Spaces - **Cold starts are normal**: the first request after restart can be slow because Gemini clients need initialization - **Do not rely on local disk durability** unless you are intentionally using persistent storage - **Keep logging at `INFO`** unless debugging, because verbose logs add noise and overhead - **Be conservative with concurrency** to avoid upstream instability and Space timeouts - If you expose the built-in web UI, remember that it is still best treated as a personal/internal interface ### Security Reminder For self-use deployments, it is still a good idea to avoid storing the following directly in version-controlled files: - `server.api_key` - `gemini.clients[*].secure_1psid` - `gemini.clients[*].secure_1psidts` Use Space Secrets whenever possible. ## Docker Deployment ### Run with Options ```bash docker run -p 8000:8000 \ -v $(pwd)/data:/app/data \ -v $(pwd)/cache:/app/cache \ -e CONFIG_SERVER__API_KEY="your-api-key-here" \ -e CONFIG_GEMINI__CLIENTS__0__ID="client-a" \ -e CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID="your-secure-1psid" \ -e CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="your-secure-1psidts" \ -e GEMINI_COOKIE_PATH="/app/cache" \ ghcr.io/nativu5/gemini-fastapi ``` > [!TIP] > Add `CONFIG_GEMINI__CLIENTS__N__PROXY` only if you need a proxy; omit the variable to keep direct connections. > > `GEMINI_COOKIE_PATH` points to the directory inside the container where refreshed cookies are stored. Bind-mounting it (e.g. `-v $(pwd)/cache:/app/cache`) preserves those cookies across container rebuilds/recreations so you rarely need to re-authenticate. ### Run with Docker Compose Create a `docker-compose.yml` file: ```yaml services: gemini-fastapi: image: ghcr.io/nativu5/gemini-fastapi:latest ports: - "8000:8000" volumes: # - ./config:/app/config # Uncomment to use a custom config file # - ./certs:/app/certs # Uncomment to enable HTTPS with your certs - ./data:/app/data - ./cache:/app/cache environment: - CONFIG_SERVER__HOST=0.0.0.0 - CONFIG_SERVER__PORT=8000 - CONFIG_SERVER__API_KEY=${API_KEY} - CONFIG_GEMINI__CLIENTS__0__ID=client-a - CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID=${SECURE_1PSID} - CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS=${SECURE_1PSIDTS} - GEMINI_COOKIE_PATH=/app/cache # must match the cache volume mount above restart: on-failure:3 # Avoid retrying too many times ``` Then run: ```bash docker compose up -d ``` > [!IMPORTANT] > Make sure to mount the `/app/data` volume to persist conversation data between container restarts. > Also mount `/app/cache` so refreshed cookies (including rotated 1PSIDTS values) survive container rebuilds/recreates without re-auth. ## Configuration The server reads a YAML configuration file located at `config/config.yaml`. For details on each configuration option, refer to the comments in the [`config/config.yaml`](https://github.com/Nativu5/Gemini-FastAPI/blob/main/config/config.yaml) file. ### Environment Variable Overrides > [!TIP] > This feature is particularly useful for Docker deployments and production environments where you want to keep sensitive credentials separate from configuration files. You can override any configuration option using environment variables with the `CONFIG_` prefix. Use double underscores (`__`) to represent nested keys, for example: ```bash # Override server settings export CONFIG_SERVER__API_KEY="your-secure-api-key" # Override Gemini credentials for client 0 export CONFIG_GEMINI__CLIENTS__0__ID="client-a" export CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID="your-secure-1psid" export CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="your-secure-1psidts" # Override optional proxy settings for client 0 export CONFIG_GEMINI__CLIENTS__0__PROXY="socks5://127.0.0.1:1080" # Override conversation storage size limit export CONFIG_STORAGE__MAX_SIZE=268435456 # 256 MB ``` ### Client IDs and Conversation Reuse Conversations are stored with the ID of the client that generated them. Keep these identifiers stable in your configuration so that sessions remain valid when you update the cookie list. ### Gemini Credentials > [!WARNING] > Keep these credentials secure and never commit them to version control. These cookies provide access to your Google account. To use Gemini-FastAPI, you need to extract your Gemini session cookies: 1. Open [Gemini](https://gemini.google.com/) in a private/incognito browser window and sign in 2. Open Developer Tools (F12) 3. Navigate to **Application** β†’ **Storage** β†’ **Cookies** 4. Find and copy the values for: - `__Secure-1PSID` - `__Secure-1PSIDTS` > [!TIP] > For detailed instructions, refer to the [HanaokaYuzu/Gemini-API authentication guide](https://github.com/HanaokaYuzu/Gemini-API?tab=readme-ov-file#authentication). ### Proxy Settings Each client entry can be configured with a different proxy to work around rate limits. Omit the `proxy` field or set it to `null` or an empty string to keep a direct connection. ### Chat Session Mode You can control whether requests use normal Google chats or Google's temporary chat mode: ```yaml gemini: chat_mode: "normal" # "normal" (reuse metadata) or "temporary" (Google temporary chat, not saved to account) max_chars_per_request: 1000000 oversized_context_strategy: "compaction" # "compaction" or "file" ``` When `chat_mode` is set to `temporary`, the server applies an internal effective input limit of 90% of `max_chars_per_request`. When context exceeds the effective budget, handling is controlled by `oversized_context_strategy`: - `compaction`: summarize older turns and keep recent turns verbatim. - `file`: attach oversized context as `message.txt` and process it from file. Environment variable equivalents: ```bash export CONFIG_GEMINI__CHAT_MODE="temporary" export CONFIG_GEMINI__MAX_CHARS_PER_REQUEST=1000000 export CONFIG_GEMINI__OVERSIZED_CONTEXT_STRATEGY="compaction" ``` ### Custom Models You can define custom models in `config/config.yaml` or via environment variables. #### YAML Configuration ```yaml gemini: model_strategy: "append" # "append" (default + custom) or "overwrite" (custom only) models: - model_name: "gemini-3.0-pro" model_header: x-goog-ext-525001261-jspb: '[1,null,null,null,"9d8ca3786ebdfbea",null,null,0,[4],null,null,1]' ``` #### Environment Variables You can supply models as a JSON string or list structure via `CONFIG_GEMINI__MODELS`. This provides a flexible way to override settings via the shell or in automated environments (e.g. Docker) without modifying the configuration file. ```bash export CONFIG_GEMINI__MODEL_STRATEGY="overwrite" export CONFIG_GEMINI__MODELS='[{"model_name": "gemini-3.0-pro", "model_header": {"x-goog-ext-525001261-jspb": "[1,null,null,null,\"9d8ca3786ebdfbea\",null,null,0,[4],null,null,1]"}}]' ``` ## Acknowledgments - [HanaokaYuzu/Gemini-API](https://github.com/HanaokaYuzu/Gemini-API) - The underlying Gemini web API client - [zhiyu1998/Gemi2Api-Server](https://github.com/zhiyu1998/Gemi2Api-Server) - This project originated from this repository. After extensive refactoring and engineering improvements, it has evolved into an independent project, featuring multi-turn conversation reuse among other enhancements. Special thanks for the inspiration and foundational work provided. ## Disclaimer This project is not affiliated with Google or OpenAI and is intended solely for educational and research purposes. It uses reverse-engineered APIs and may not comply with Google's Terms of Service. Use at your own risk.