DOCSEARCHbyAlgolia
Submit Docs

Gemini-FastAPI

repository·main·Indexed 20 days ago

https://github.com/nativu5/gemini-fastapi

A FastAPI server that acts as a web-based Gemini model wrapper, providing an OpenAI-compatible API. It allows access to Gemini's web-based capabilities using Google session cookies (__Secure-1PSID and __Secure-1PSIDTS) instead of official API keys. Features include support for streaming, multi-modal inputs (text, images, files), tool calling, structured JSON output, and custom model definitions.

Tokens
5K
Snippets
19
Records
24
Agent score
72%

What's inside gemini-fastapi

  1. Rotate LMDB records using rotate_lmdb.py

    main

    Use the rotate_lmdb.py script to perform maintenance on an LMDB database by deleting old records or clearing the database entirely.

    Arguments:

    • <path_to_lmdb>: The file path to the LMDB database.
    • <duration_or_all>:
      • A duration string (e.g., 14d for 14 days) to delete entries older than that period.
      • The literal string all to remove all records from the database.
    # Delete entries older than 14 days
python scripts/rotate_lmdb.py /path/to/lmdb 14d

# Delete all entries
python scripts/rotate_lmdb.py /path/to/lmdb all

  2. Configure Gemini credentials using cookies

    main

    Gemini-FastAPI uses web-based Gemini models via session cookies instead of an API key. You must provide secure_1psid and secure_1psidts cookies extracted from your Google account.

    How to extract cookies:

    1. Open Gemini in a private/incognito browser window and sign in.
    2. Open Developer Tools (F12).
    3. Navigate to Application → Storage → Cookies.
    4. Copy the values for __Secure-1PSID and __Secure-1PSIDTS.

    Configuration via YAML

    Edit config/config.yaml to add your credentials:

    gemini:
  clients:
    - id: "client-a"
      secure_1psid: "YOUR_SECURE_1PSID_HERE"
      secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE"
      proxy: null # Optional proxy URL
    gemini:
  clients:
    - id: "client-a"
      secure_1psid: "YOUR_SECURE_1PSID_HERE"
      secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE"
      proxy: null

  3. Deploy Gemini-FastAPI with Docker

    main

    You can deploy the server using Docker or Docker Compose.

    Docker Run

    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

    Docker Compose

    Create a docker-compose.yml:

    services:
  gemini-fastapi:
    image: ghcr.io/nativu5/gemini-fastapi:latest
    ports:
      - "8000:8000"
    volumes:
      - ./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
    restart: on-failure:3

    Important Notes:

    • Mount /app/data to persist conversation data.
    • Mount /app/cache to preserve refreshed cookies (including rotated 1PSIDTS values) so you don't have to re-authenticate.

  4. Install Gemini-FastAPI via uv or pip

    main

    You can install Gemini-FastAPI by cloning the repository and using either uv (recommended) or pip.

    Using uv:

    git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
uv sync

    Using pip:

    git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
pip install -e .
    git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
uv sync

  5. Dump LMDB records using dump_lmdb.py

    main

    Use the dump_lmdb.py script to export records from an LMDB database into a JSON array. You can export the entire database or filter for specific keys.

    Arguments:

    • <path_to_lmdb>: The file path to the LMDB database.
    • [key1 key2 ...] (optional): Specific keys to retrieve. If omitted, all records are returned.
    # Dump all entries
python scripts/dump_lmdb.py /path/to/lmdb

# Dump specific keys
python scripts/dump_lmdb.py /path/to/lmdb key1 key2

  7. Install Gemini-FastAPI

    main

    You can install Gemini-FastAPI using uv (recommended) or pip.

    Using uv (Recommended)

    git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
uv sync

    Using pip

    git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
pip install -e .

  8. Run the Gemini-FastAPI server

    main

    After installation and configuration, you can start the server using uv or standard python.

    # Using uv
uv run python run.py

# Using Python directly
python run.py

    By default, the server runs on http://localhost:8000.

    uv run python run.py

  9. Understand the application lifespan and background tasks

    main

    The gemini-fastapi application uses a FastAPI lifespan manager to handle startup and shutdown logic.

    Startup Sequence

    1. GeminiClientPool Initialization: The GeminiClientPool is initialized. If initialization fails, the application will raise an exception and fail to start.
    2. Retention Cleanup Task: A background task _run_retention_cleanup is started. This task periodically (every 6 hours by default) enforces the LMDB retention policy and cleans up expired images.
    3. Error Checking: The startup process waits briefly (await asyncio.sleep(0)) to ensure the cleanup task starts successfully and surfaces any immediate failures.

    Shutdown Sequence

    1. Stop Signal: A stop_event is set to signal the background cleanup task to stop.
    2. Task Completion: The application waits for the cleanup_task to finish gracefully before completing the shutdown process.

  10. Override configuration using environment variables

    main

    For Docker or production environments, you can override any configuration setting using environment variables with the CONFIG_ prefix. Nested keys are separated by double underscores (__).

    Examples:

    • CONFIG_SERVER__API_KEY: Overrides the server API key.
    • CONFIG_GEMINI__CLIENTS__0__ID: Overrides the ID for the first client.
    • CONFIG_GEMINI__CLIENTS__0__PROXY: Sets a proxy for the first client.
    • CONFIG_STORAGE__MAX_SIZE: Sets the maximum size for conversation storage.
    export CONFIG_SERVER__API_KEY="your-secure-api-key"
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"
export CONFIG_GEMINI__CLIENTS__0__PROXY="socks5://127.0.0.1:1080"
export CONFIG_STORAGE__MAX_SIZE=268435456

  11. Override configuration with environment variables

    main

    You can override any configuration option using environment variables with the CONFIG_ prefix. Use double underscores (__) for nested keys.

    Examples:

    • CONFIG_SERVER__API_KEY: Overrides server API key.
    • CONFIG_GEMINI__CLIENTS__0__ID: Overrides the ID for the first Gemini client.
    • CONFIG_STORAGE__MAX_SIZE: Overrides conversation storage size limit.

    This is highly recommended for Docker deployments to keep credentials out of config files.

    # 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"

  12. Configure Gemini credentials in config.yaml

    main

    To use the service, you must provide Google Gemini web cookies. Edit config/config.yaml and add at least one client entry. You need to extract secure_1psid and secure_1psidts from your browser's cookies while logged into Gemini.

    Each client can optionally have its own proxy URL to help avoid rate limits.

    gemini:
  clients:
    - id: "client-a"
      secure_1psid: "YOUR_SECURE_1PSID_HERE"
      secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE"
      proxy: null # Optional proxy URL