gemBridge

A lightweight HTTP bridge that lets you call Google Gemini Gems (custom AI personas)
from any HTTP client -- n8n, curl, or your own code -- without re-sending large system
prompts on every request.

Why This Exists

The official Gemini API does not expose Gem IDs. Without gemBridge, you must include your
full system prompt and persona instructions in every API call, which is verbose, expensive,
and error-prone. gemBridge authenticates via browser session cookies (using
HanaokaYuzu/Gemini-API) and forwards requests
to the correct Gem on your behalf.

Note: This approach depends on Google browser session cookies that expire every 2-4
weeks. Cookie rotation takes about 2 minutes and is the main ongoing maintenance task.
Best treated as a personal or internal tool rather than a public-facing service.

Features

• Target any Gem by ID in a single POST request
• Runs in Docker (recommended) or directly via Python venv + systemd
• Cookie hot-reload via /reload -- no restart needed when cookies expire
• File-based logging with daily rotation (7-day retention)
• Debug drop-file: enable full request/response dumps with touch .debug
• /health endpoint for monitoring and uptime checks

Requirements

• Linux (Ubuntu 22.04+ recommended)
• A Google account with access to gemini.google.com
• Docker (PATH A) or Python 3.10+ (PATH B)

Quick Start

1. Get the code

git clone ssh://theitguys@git.code.sf.net/p/call-a-gemini-gem-from-api/code gemBridge
cd gemBridge

2. Create your config file

cp .env.template .env

3. Add your Google cookies

Edit .env and fill in the two cookie values:

__Secure_1PSID=your_value_here
__Secure_1PSIDTS=your_value_here

See docs/cookies.md for step-by-step instructions on getting these values.

4. Start the server

Docker (recommended):

docker compose up -d

Direct (Python venv + systemd):

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
./start.sh

For full setup instructions including success indicators at each step, see
docs/setup.md.

Usage

Send a prompt (no Gem)

curl -s -X POST http://127.0.0.1:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarise this in one sentence: ..."}'

Send a prompt to a specific Gem

curl -s -X POST http://127.0.0.1:8000/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Draft a reply to this email: ...",
    "gemId": "your-gem-id-here"
  }'

Response format

{ "text": "Here is the response from Gemini..." }

Health check

curl -s http://127.0.0.1:8000/health

{
  "status": "ok",
  "uptime_seconds": 3600,
  "debug_mode": false,
  "psid_configured": true
}

If psid_configured is false, your cookies have expired. See
docs/operations.md for rotation steps.

Reload cookies (after updating .env)

curl -s -X POST http://127.0.0.1:8000/reload

Request Schema

Configuration

All configuration lives in .env in the project root. This file is gitignored and never
committed. Copy .env.template to get started.

Docs

n8n Integration

Add an HTTP Request node:

The response contains { "text": "..." } -- reference it downstream as {{ $json.text }}.

See docs/n8n.md for the full guide including importing via cURL.

License

This project is released under the MIT License.

The gemini-webapi dependency is licensed under the GNU Affero General Public License v3.