Spaces:
Runtime error
Download README.md from 520superxu520/G_AI: direct link, hf CLI and curl.
- Browser
- Download file 11 kB
-
https://huggingface.co/spaces/520superxu520/G_AI/resolve/main/README.md
- Command line
-
hf download hf://spaces/520superxu520/G_AI/README.md
-
curl -L -o README.md https://huggingface.co/spaces/520superxu520/G_AI/resolve/main/README.md
title: G_AI
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
Gemini-FastAPI
[ English | 中文 ]
Web-based Gemini models wrapped into an OpenAI-compatible API. Powered by 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 section below.
Prerequisites
- Python 3.12
- Google account with Gemini access on web
secure_1psidandsecure_1psidtscookies from Gemini web interface
Installation
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 .
Configuration
Edit config/config.yaml and provide at least one credential pair:
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)
For details, refer to the Configuration section below.
Running the Server
# 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
- Duplicate
config/config.yamllocally as a private working config, or create your ownconfig/config.example.yaml-based config - Store sensitive values in Space Secrets
- Keep persistent data expectations modest on free Spaces:
data/lmdbmay be reset when the Space is rebuilt- refreshed cookies stored in cache directories should not be treated as permanent
- Use a small number of Gemini web clients unless you really need more, to reduce cold-start and initialization time
Recommended Space Secrets / Variables
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
INFOunless 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_keygemini.clients[*].secure_1psidgemini.clients[*].secure_1psidts
Use Space Secrets whenever possible.
Docker Deployment
Run with Options
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
Add
CONFIG_GEMINI__CLIENTS__N__PROXYonly if you need a proxy; omit the variable to keep direct connections.
GEMINI_COOKIE_PATHpoints 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:
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:
docker compose up -d
Make sure to mount the
/app/datavolume to persist conversation data between container restarts. Also mount/app/cacheso 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 file.
Environment Variable Overrides
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:
# 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
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:
- Open Gemini in a private/incognito browser window and sign in
- Open Developer Tools (F12)
- Navigate to Application → Storage → Cookies
- Find and copy the values for:
__Secure-1PSID__Secure-1PSIDTS
For detailed instructions, refer to the HanaokaYuzu/Gemini-API authentication guide.
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:
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 asmessage.txtand process it from file.
Environment variable equivalents:
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
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.
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 - The underlying Gemini web API client
- 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.