geminicli2api

You can deploy the proxy using Docker. You must provide a GEMINI_AUTH_PASSWORD for API access and one of the Google credential sources.

To run on the default port 8888:

docker run -p 8888:8888 \
  -e GEMINI_AUTH_PASSWORD=your_password \
  -e GEMINI_CREDENTIALS='{"client_id":"...","token":"..."}' \
  -e PORT=8888 \
  geminicli2api

To run on port 7680 (compatible with Hugging Face Spaces):

docker run -p 7680:7680 \
  -e GEMINI_AUTH_PASSWORD=your_password \
  -e GEMINI_CREDENTIALS='{"client_id":"...","token":"..."}' \
  -e PORT=7680 \
  geminicli2api

# Build the image
docker build -t geminicli2api .

# Run on default port 8888 (compatibility)
docker run -p 8888:8888 \
  -e GEMINI_AUTH_PASSWORD=your_password \
  -e GEMINI_CREDENTIALS='{"client_id":"...","token":"..."}' \
  -e PORT=8888 \
  geminicli2api

The proxy requires specific environment variables for authentication and Google credentials.

Required:

• GEMINI_AUTH_PASSWORD: The password used for API authentication.

Optional Credential Sources (Choose one):

• GEMINI_CREDENTIALS: A JSON string containing Google OAuth credentials.
• GOOGLE_APPLICATION_CREDENTIALS: Path to a Google OAuth credentials file.
• GOOGLE_CLOUD_PROJECT: Google Cloud project ID.
• GEMINI_PROJECT_ID: Alternative project ID variable.

Example GEMINI_CREDENTIALS JSON structure:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret", 
  "token": "your-access-token",
  "refresh_token": "your-refresh-token",
  "scopes": ["https://www.googleapis.com/auth/cloud-platform"],
  "token_uri": "https://oauth2.googleapis.com/token"
}

You can deploy geminicli2api using Docker Compose. The service exposes several environment variables for authentication, Google Cloud configuration, and network settings. By default, the service listens on port 8888 and binds to 0.0.0.0.

services:
  geminicli2api:
    build: .
    ports:
      - "${PORT:-8888}:${PORT:-8888}"
    environment:
      - GEMINI_AUTH_PASSWORD=${GEMINI_AUTH_PASSWORD:-your_password_here}
      - GEMINI_CREDENTIALS=${GEMINI_CREDENTIALS:-}
      - GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT:-}
      - GOOGLE_APPLICATION_CREDENTIALS=${GOOGLE_APPLICATION_CREDENTIALS:-}
      - HOST=${HOST:-0.0.0.0}
      - PORT=${PORT:-8888}
    volumes:
      - ${GOOGLE_APPLICATION_CREDENTIALS:-/dev/null}:/app/${GOOGLE_APPLICATION_CREDENTIALS:-oauth_creds.json}:ro

The application is built using FastAPI and initializes by loading environment variables from a .env file and configuring CORS to allow all origins (*).

During startup, the server attempts to locate credentials in one of two ways:

1. The GEMINI_CREDENTIALS environment variable.
2. A local credentials file (defined by CREDENTIAL_FILE in the config module).

If no credentials are found, the server attempts an OAuth authentication flow. If credentials are successfully loaded, the server performs an onboarding process using onboard_user with the retrieved project ID.

The application is a FastAPI server that can be run directly as a Python script. It uses uvicorn to serve the app instance imported from src.main. You can configure the network interface and port using the HOST and PORT environment variables.

# To run the server manually via command line (assuming app.py is in your path):
python app.py

# Or using uvicorn directly:
uvicorn app:app --host 0.0.0.0 --port 7860

The proxy supports native Gemini API endpoints, including content generation and streaming. You can pass Google-specific configurations like thinkingConfig directly in the request body.

import requests

headers = {
    "Authorization": "Bearer your_password",
    "Content-Type": "application/json"
}

data = {
    "contents": [
        {
            "role": "user",
            "parts": [{"text": "Explain the theory of relativity in simple terms."}]
        }
    ],
    "thinkingConfig": {
        "thinkingBudget": 32768,
        "includeThoughts": True
    }
}

response = requests.post(
    "http://localhost:8888/v1beta/models/gemini-2.5-pro:generateContent",  # or 7680 for HF
    headers=headers,
    json=data
)

print(response.json())

You can provide credentials to the proxy without using a local file by setting the GEMINI_CREDENTIALS environment variable. This variable must contain a valid JSON string representing the OAuth2 credentials.

The proxy supports several formats within this JSON, including mapping access_token to token and splitting scope into scopes. If a refresh_token is present, the proxy will attempt to refresh the credentials automatically if they are expired.

Additionally, you can set GOOGLE_CLOUD_PROJECT to specify the project ID used for API calls.

export GEMINI_CREDENTIALS='{"client_id": "...", "client_secret": "...", "refresh_token": "...", "project_id": "my-project"}'
export GOOGLE_CLOUD_PROJECT="my-project"

The proxy supports several base models and allows you to create specialized variants by appending suffixes to the model name.

Base Models:

• gemini-2.5-pro
• gemini-2.5-flash
• gemini-1.5-pro
• gemini-1.5-flash
• gemini-1.0-pro

Model Variants:

• -search: Enables Google Search grounding (e.g., gemini-2.5-pro-search).
• -nothinking: Minimizes reasoning steps (e.g., gemini-2.5-flash-nothinking).
• -maxthinking: Maximizes the reasoning budget (e.g., gemini-2.5-pro-maxthinking).

The API supports four authentication methods using the value provided in GEMINI_AUTH_PASSWORD:

1. Bearer Token: Authorization: Bearer YOUR_PASSWORD
2. Basic Auth: Authorization: Basic base64(username:YOUR_PASSWORD)
3. Query Parameter: ?key=YOUR_PASSWORD
4. Google Header: x-goog-api-key: YOUR_PASSWORD

OpenAI-Compatible Endpoints

• POST /v1/chat/completions - Chat completions (streaming & non-streaming)
• GET /v1/models - List available models

Native Gemini Endpoints

• GET /v1beta/models - List Gemini models
• POST /v1beta/models/{model}:generateContent - Generate content
• POST /v1beta/models/{model}:streamGenerateContent - Stream content
• Note: All other Gemini API endpoints are proxied through.

Utility Endpoints

• GET /health - Health check for container orchestration