AstraSunday/geminicli2api

1---2title: Gemini CLI to API Proxy3emoji: 🤖4colorFrom: blue5colorTo: purple6sdk: docker7pinned: false8license: mit9app_port: 786010---11 12# Gemini CLI to API Proxy (geminicli2api)13 14A FastAPI-based proxy server that converts the Gemini CLI tool into both OpenAI-compatible and native Gemini API endpoints. This allows you to leverage Google's free Gemini API quota through familiar OpenAI API interfaces or direct Gemini API calls.15 16## 🚀 Features17 18- **OpenAI-Compatible API**: Drop-in replacement for OpenAI's chat completions API19- **Native Gemini API**: Direct proxy to Google's Gemini API20- **Streaming Support**: Real-time streaming responses for both API formats21- **Multimodal Support**: Text and image inputs22- **Authentication**: Multiple auth methods (Bearer, Basic, API key)23- **Google Search Grounding**: Enable Google Search for grounded responses using `-search` models.24- **Thinking/Reasoning Control**: Control Gemini's thinking process with `-nothinking` and `-maxthinking` models.25- **Docker Ready**: Containerized for easy deployment26- **Hugging Face Spaces**: Ready for deployment on Hugging Face27 28## 🔧 Environment Variables29 30### Required31- `GEMINI_AUTH_PASSWORD`: Authentication password for API access32 33### Optional Credential Sources (choose one)34- `GEMINI_CREDENTIALS`: JSON string containing Google OAuth credentials35- `GOOGLE_APPLICATION_CREDENTIALS`: Path to Google OAuth credentials file36- `GOOGLE_CLOUD_PROJECT`: Google Cloud project ID37- `GEMINI_PROJECT_ID`: Alternative project ID variable38 39### Example Credentials JSON40```json41{42  "client_id": "your-client-id",43  "client_secret": "your-client-secret", 44  "token": "your-access-token",45  "refresh_token": "your-refresh-token",46  "scopes": ["https://www.googleapis.com/auth/cloud-platform"],47  "token_uri": "https://oauth2.googleapis.com/token"48}49```50 51## 📡 API Endpoints52 53### OpenAI-Compatible Endpoints54- `POST /v1/chat/completions` - Chat completions (streaming & non-streaming)55- `GET /v1/models` - List available models56 57### Native Gemini Endpoints  58- `GET /v1beta/models` - List Gemini models59- `POST /v1beta/models/{model}:generateContent` - Generate content60- `POST /v1beta/models/{model}:streamGenerateContent` - Stream content61- All other Gemini API endpoints are proxied through62 63### Utility Endpoints64- `GET /health` - Health check for container orchestration65 66## 🔐 Authentication67 68The API supports multiple authentication methods:69 701. **Bearer Token**: `Authorization: Bearer YOUR_PASSWORD`712. **Basic Auth**: `Authorization: Basic base64(username:YOUR_PASSWORD)`723. **Query Parameter**: `?key=YOUR_PASSWORD`734. **Google Header**: `x-goog-api-key: YOUR_PASSWORD`74 75## 🐳 Docker Usage76 77```bash78# Build the image79docker build -t geminicli2api .80 81# Run on default port 8888 (compatibility)82docker run -p 8888:8888 \83  -e GEMINI_AUTH_PASSWORD=your_password \84  -e GEMINI_CREDENTIALS='{"client_id":"...","token":"..."}' \85  -e PORT=8888 \86  geminicli2api87 88# Run on port 7860 (Hugging Face compatible)89docker run -p 7860:7860 \90  -e GEMINI_AUTH_PASSWORD=your_password \91  -e GEMINI_CREDENTIALS='{"client_id":"...","token":"..."}' \92  -e PORT=7860 \93  geminicli2api94```95 96### Docker Compose97 98```bash99# Default setup (port 8888)100docker-compose up -d101 102# Hugging Face setup (port 7860)103docker-compose --profile hf up -d geminicli2api-hf104```105 106## 🤗 Hugging Face Spaces107 108This project is configured for Hugging Face Spaces deployment:109 1101. Fork this repository1112. Create a new Space on Hugging Face1123. Connect your repository1134. Set the required environment variables in Space settings:114   - `GEMINI_AUTH_PASSWORD`115   - `GEMINI_CREDENTIALS` (or other credential source)116 117The Space will automatically build and deploy using the included Dockerfile.118 119## 📝 OpenAI API Example120 121```python122import openai123 124# Configure client to use your proxy125client = openai.OpenAI(126    base_url="http://localhost:8888/v1",  # or 7860 for HF127    api_key="your_password"  # Your GEMINI_AUTH_PASSWORD128)129 130# Use like normal OpenAI API131response = client.chat.completions.create(132    model="gemini-2.5-pro-maxthinking",133    messages=[134        {"role": "user", "content": "Explain the theory of relativity in simple terms."}135    ],136    stream=True137)138 139# Separate reasoning from the final answer140for chunk in response:141    if chunk.choices[0].delta.reasoning_content:142        print(f"Thinking: {chunk.choices[0].delta.reasoning_content}")143    if chunk.choices[0].delta.content:144        print(chunk.choices[0].delta.content, end="")145```146 147## 🔧 Native Gemini API Example148 149```python150import requests151 152headers = {153    "Authorization": "Bearer your_password",154    "Content-Type": "application/json"155}156 157data = {158    "contents": [159        {160            "role": "user",161            "parts": [{"text": "Explain the theory of relativity in simple terms."}]162        }163    ],164    "thinkingConfig": {165        "thinkingBudget": 32768,166        "includeThoughts": True167    }168}169 170response = requests.post(171    "http://localhost:8888/v1beta/models/gemini-2.5-pro:generateContent",  # or 7860 for HF172    headers=headers,173    json=data174)175 176print(response.json())177```178 179## 🎯 Supported Models180 181### Base Models182- `gemini-2.5-pro`183- `gemini-2.5-flash`184- `gemini-1.5-pro`185- `gemini-1.5-flash`186- `gemini-1.0-pro`187 188### Model Variants189The proxy automatically creates variants for `gemini-2.5-pro` and `gemini-2.5-flash` models:190 191- **`-search`**: Appends `-search` to a model name to enable Google Search grounding.192  - Example: `gemini-2.5-pro-search`193- **`-nothinking`**: Appends `-nothinking` to minimize reasoning steps.194  - Example: `gemini-2.5-flash-nothinking`195- **`-maxthinking`**: Appends `-maxthinking` to maximize the reasoning budget.196  - Example: `gemini-2.5-pro-maxthinking`197 198## 📄 License199 200MIT License - see LICENSE file for details.201 202## 🤝 Contributing203 204Contributions are welcome! Please feel free to submit a Pull Request.