api-for-gemini 1.4.2

Gemini API proxy for routing requests to Google or OpenAI-compatible backends

API for Gemini

English | 中文

A lightweight API proxy that receives Google Gemini API requests and routes them to Gemini, OpenAI-compatible, or DeepSeek backends based on config.toml rules. Designed primarily for use with Gemini CLI, enabling you to use any LLM provider as the backend.

Features

• Multi-backend support — Route requests to Gemini, OpenAI, DeepSeek, or any OpenAI-compatible endpoint (e.g. Ollama, vLLM)
• Model routing — Transparently map model names to different backends via transfer rules
• Streaming & non-streaming — Full support for both SSE streaming and standard request/response
• Tool calls — Transparent function calling / tool use conversion between Gemini and OpenAI formats
• Thinking support — DeepSeek reasoning_content is mapped to Gemini's thought parts
• Zero-config Gemini CLI integration — gema setup writes hooks so the proxy auto-starts with Gemini CLI

Requirements

• Python 3.10+

Installation

Using uv (recommended):

uv tool install api-for-gemini

Using pip:

pip install api-for-gemini

After installation, the gema CLI command is available.

Quick Start

1. Create Configuration

gema config -n

This creates config.toml in the current directory. Edit it with your API keys and model mappings:

[provider.google]
template = "gemini"
api_url = "https://generativelanguage.googleapis.com"
api_key = "YOUR_GEMINI_API_KEY"

[provider.openai_official]
template = "openai"
api_url = "https://api.openai.com/v1"
api_key = "YOUR_OPENAI_API_KEY"

[provider.deepseek_official]
template = "deepseek"
api_url = "https://api.deepseek.com/v1"
api_key = "YOUR_DEEPSEEK_API_KEY"

[model.gemini-2-5-flash]
provider = "google"
model = "gemini-2.5-flash"

[model.gpt-4o]
provider = "openai_official"
model = "gpt-4o"

[model.ds-chat]
provider = "deepseek_official"
model = "deepseek-chat"

[model.local-llama]
template = "openai"
api_url = "http://localhost:11434/v1"
model = "llama3"

[[transfer]]
make = "gemini-pro"
to = "gemini-2-5-flash"

[[transfer]]
make = "gpt-4"
to = "ds-chat"

2. Start the Proxy

gema start

The server runs on http://127.0.0.1:18000.

For development with hot reload:

gema start --debug

3. Use with Gemini CLI

1. Auto-start setup (Recommended): Run the following command to write a gema-context hook to your global Gemini CLI settings. This ensures the proxy auto-starts whenever you launch Gemini CLI from any directory.

gema setup -g

2. Configure Environment: Set the GOOGLE_GEMINI_BASE_URL environment variable to point to the proxy:

# Windows (PowerShell) - Current Session
$env:GOOGLE_GEMINI_BASE_URL = "http://127.0.0.1:18000"
# Windows (PowerShell) - Persistent (User level)
[Environment]::SetEnvironmentVariable("GOOGLE_GEMINI_BASE_URL", "http://127.0.0.1:18000", "User")

# Linux / macOS - Current Session
export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:18000"
# Linux / macOS - Persistent (Add to ~/.bashrc or ~/.zshrc)
echo 'export GOOGLE_GEMINI_BASE_URL="http://127.0.0.1:18000"' >> ~/.zshrc

3. Gemini CLI Auth: Inside the Gemini CLI session, run the /auth command:
   • Select "2. Use Gemini API Key".
   • Enter any string as the API key (the actual keys are managed in your config.toml).

CLI Reference

gema setup [-g|--global] [-l|--local] [-c CONFIG_PATH]   # Initialize config + Gemini CLI hooks
gema config -n [PATH]                                     # Create a new config file
gema start [-c CONFIG_PATH] [-d|--debug]                  # Start the proxy server
gema context                                               # Output JSON context (used by Gemini CLI hooks)

Command	Description
gema setup -l	Create config.toml + write hook to local .gemini/settings.json
gema setup -g	Create config.toml + write hook to global ~/.gemini/settings.json
gema config -n ./my-config.toml	Create config at a specific path
gema start -c ./my-config.toml	Start server with a custom config file
gema start --debug	Start server with hot reload (watches api_for_gemini/server/)

Config Search Order

When no explicit -c flag is provided, gema start looks for config files in this order:

1. ./config.toml (current working directory)
2. ./.gemini/config.toml (local project config)
3. ~/.gemini/config.toml (global config)

Configuration Reference

Providers ([provider.ID])

Define reusable backend connections:

Field	Description
template	Backend type: "gemini", "openai", or "deepseek"
api_url	Base URL of the API endpoint
api_key	API key for authentication

Models ([model.NAME])

Define available models, optionally inheriting from a provider:

Field	Description
provider	Reference to a [provider.ID] (inherits template, api_url, api_key)
model	Actual model name sent to the backend
template	Backend type (required if no provider)
api_url	API endpoint (required if no provider)
api_key	API key (required if no provider)

Transfers ([[transfer]])

Route one model name to another. The make field supports the * wildcard for flexible matching (prefix, suffix, or middle):

[[transfer]]
make = "gemini-pro"      # Incoming request model name
to = "gemini-2-5-flash"  # Actual model to route to

[[transfer]]
make = "gpt-4*"          # Suffix matching: gpt-4, gpt-4-turbo, gpt-4o, etc.
to = "ds-chat"

[[transfer]]
make = "h*d"             # Middle matching: Matches "helloworld", "head", "hd", etc.
to = "some-model"

Architecture

Gemini CLI Request
       |
       v
  Gema Proxy (FastAPI, :18000)
       |
       +-- ConfigManager.resolve_model() --> ModelSchema
       |
       +-- ClientRequest.build() --> GoogleRequest / OpenaiRequest / DeepseekRequest
       |
       +-- Backend API Call (Gemini / OpenAI / DeepSeek)
       |
       +-- Response conversion back to Gemini format
       |
       v
  Gemini CLI receives response

API Endpoints

Method	Path	Description
POST	/v1beta/models/{model}:generateContent	Non-streaming generation
POST	/v1beta/models/{model}:streamGenerateContent	SSE streaming generation
GET	/status	Health check

All endpoints accept and return Gemini API wire format, regardless of the backend being used.

License

MIT