Gemini API Relay
Production-grade interface for Gemini Web API supporting text generation, image synthesis, vision input, and stateful conversations.
Overview
This relay provides programmatic access to Gemini's multimodal capabilities through a reverse-engineered Web API client. Supports all major Gemini 3.x models including Flash, Pro, and experimental variants.
Key Features:
- Text generation with multiple model backends
- Image synthesis from natural language prompts
- Vision-based analysis using reference images
- Session-based multi-turn conversations
- Flexible authentication with browser cookie reuse
Script Architecture
All executable components reside in the scripts/ subdirectory relative to this skill file.
Path Resolution Protocol:
- Identify this SKILL.md location as
{baseDir} - Construct script paths:
{baseDir}/scripts/<script-name>.ts - Resolve runtime:
bun(if installed) →${BUN_X}=bun, otherwisenpx -y bun - Substitute
{baseDir}and${BUN_X}in all command examples below
Core Scripts:
scripts/main.ts— Primary CLI interfacescripts/gemini-webapi/*— TypeScript API client implementation
Consent Requirements
Initial use requires explicit user acceptance of reverse-engineered API terms.
Consent Storage Paths:
- macOS:
~/Library/Application Support/baoyu-skills/gemini-web/consent.json - Linux:
~/.local/share/baoyu-skills/gemini-web/consent.json - Windows:
%APPDATA%\baoyu-skills\gemini-web\consent.json
Verification Flow:
- Check for valid consent file containing
{"accepted":true, "disclaimerVersion":"1.0"} - If present → display acceptance timestamp, proceed with operations
- If absent → present disclaimer text, prompt user via
AskUserQuestion:- "Accept" → generate consent file with ISO timestamp, continue
- "Decline" → terminate with declination message
- Consent schema:
{"version":1,"accepted":true,"acceptedAt":"<ISO-8601>","disclaimerVersion":"1.0"}
Authentication
First invocation launches browser-based Google authentication. Cookies are cached for subsequent requests.
When no explicit profile directory is configured, the cookie refresh process may attach to an existing Chrome/Chromium debugging session linked to the default user profile directory. To ensure session isolation, set --profile-dir or GEMINI_WEB_CHROME_PROFILE_DIR environment variable.
Browser auto-detection supports: Chrome, Chrome Canary/Beta, Chromium, Microsoft Edge.
Manual refresh: Use --login flag
Custom browser: Set GEMINI_WEB_CHROME_PATH environment variable
Configuration Files
Check for optional EXTEND.md preference file in order of precedence:
# macOS / Linux / WSL / Git Bash
test -f .baoyu-skills/gemini-api-relay/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/gemini-api-relay/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/gemini-api-relay/EXTEND.md" && echo "user"
# PowerShell (Windows)
if (Test-Path .baoyu-skills/gemini-api-relay/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/gemini-api-relay/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/gemini-api-relay/EXTEND.md") { "user" }
| Priority | Path |
|---|---|
| 1 | .baoyu-skills/gemini-api-relay/EXTEND.md (project) |
| 2 | $HOME/.baoyu-skills/gemini-api-relay/EXTEND.md (user) |
Supported Overrides: Default model selection, proxy configuration, custom data directory paths
Usage Examples
# Basic text generation
${BUN_X} {baseDir}/scripts/main.ts "Explain quantum computing"
${BUN_X} {baseDir}/scripts/main.ts --prompt "Write a haiku" --model gemini-3-flash
# Image generation
${BUN_X} {baseDir}/scripts/main.ts --prompt "Sunset over mountains" --image landscape.png
${BUN_X} {baseDir}/scripts/main.ts --promptfiles context.md instructions.md --image diagram.png
# Vision analysis with reference images
${BUN_X} {baseDir}/scripts/main.ts --prompt "Identify architectural style" --reference building.jpg
${BUN_X} {baseDir}/scripts/main.ts --prompt "Create similar composition" --reference photo.png --image variant.png
# Stateful conversations
${BUN_X} {baseDir}/scripts/main.ts "Remember this number: 2048" --sessionId conv-alpha
${BUN_X} {baseDir}/scripts/main.ts "What was the number?" --sessionId conv-alpha
# Structured output
${BUN_X} {baseDir}/scripts/main.ts "List five colors" --json
Command-Line Options
| Flag | Purpose |
|---|---|
--prompt, -p |
Input text prompt |
--promptfiles |
Read prompt from file(s), concatenated in order |
--model, -m |
Model selection (default: gemini-3-pro) |
--image [path] |
Generate image output (default: generated.png) |
--reference, --ref |
Reference image(s) for vision tasks |
--sessionId |
Conversation session identifier |
--list-sessions |
Display saved session inventory |
--json |
Return structured JSON response |
--login |
Force authentication refresh |
--cookie-path |
Override cookie storage location |
--profile-dir |
Chrome user profile directory |
Model Catalog
| Model Identifier | Characteristics |
|---|---|
gemini-3-pro |
Default, balanced performance (3.0 Pro) |
gemini-3-flash |
High-throughput, optimized latency |
gemini-3-flash-thinking |
Extended reasoning mode |
gemini-3.1-pro-preview |
Experimental 3.1 Pro (auto-routed) |
Environment Variables
| Variable | Function |
|---|---|
GEMINI_WEB_DATA_DIR |
Base directory for session/cache data |
GEMINI_WEB_COOKIE_PATH |
Authentication cookie file location |
GEMINI_WEB_CHROME_PROFILE_DIR |
Browser profile isolation path |
GEMINI_WEB_CHROME_PATH |
Explicit browser executable |
HTTP_PROXY, HTTPS_PROXY |
Network proxy for API requests |
Session Management
Session state persists in {data_dir}/sessions/<session-id>.json.
Session Schema:
id: Unique session identifiermetadata: Gemini conversation state (internal)messages: Array of turn objects with timestampscreatedAt,updatedAt: ISO-8601 timestamps
Use --list-sessions to enumerate active sessions. Session files can be manually inspected or deleted to reset conversation history.
Extension Mechanism
Custom defaults and advanced configuration via EXTEND.md files. See Configuration Files section for resolution order and supported override parameters.