Skip to main content

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
  1. 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
  1. 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

Metadata

Release files for api-for-gemini 1.4.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for api-for-gemini 1.4.2
File Size Uploaded Provenance Actions
api_for_gemini-1.4.2.tar.gz 19.7 kB Without provenance Details for api_for_gemini-1.4.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for api-for-gemini 1.4.2
File Interpreter ABI Platform Actions
api_for_gemini-1.4.2-py3-none-any.whl Python 3 none any Details for api_for_gemini-1.4.2-py3-none-any.whl

Total release size: 51.4 kB

Release files / api_for_gemini-1.4.2.tar.gz

Download URL api_for_gemini-1.4.2.tar.gz
Size 19.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9d782bfd9fc6b2a7103e3ec9de0fb4da695d8eadc62c699137c3e15e6d4a2065
BLAKE2b-256 checksum
How to use checksums
ce4f7a45e746b4a01f5e8f8723d295523045a901e48367d78cb19c5ca9aa9ee4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.22 {"installer":{"name":"uv","version":"0.11.22","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / api_for_gemini-1.4.2-py3-none-any.whl

Download URL api_for_gemini-1.4.2-py3-none-any.whl
Size 31.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
647fe1b2f47b53d37bd1537a95009658d9d6a6c39589c1b1e665fbc55bed3412
BLAKE2b-256 checksum
How to use checksums
589098c238e3122945cf00b5c099bf430d8002333145ad51ecc49a18d5eca789
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.22 {"installer":{"name":"uv","version":"0.11.22","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for api-for-gemini 1.4.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page