geminicli2api：将 Gemini CLI 转为 OpenAI 兼容 API 的代理工具

geminicli2api 是一个基于 FastAPI 的开源代理服务器，托管在 GitHub 上。它将 Google Gemini CLI 的功能转换为 OpenAI 兼容的 API 接口，同时支持原生 Gemini API 端点。开发者可通过熟悉的 OpenAI API 格式或直接的 Gemini API 调用 Google Gemini 模型，免费使用 Google 提供的 API 配额。项目支持文本生成、多模态输入（如文本和图像）、实时流式响应等功能。它提供多种认证方式，适合快速部署到本地或云端，广泛应用于开发、测试和生产环境。geminicli2api 设计轻量，易于配置，特别适合需要将 Gemini 能力集成到现有工作流的开发者。

功能列表

• 提供 OpenAI 兼容的 /v1/chat/completions 和 /v1/models 端点，适配现有 OpenAI 工具。
• 支持原生 Gemini API 端点，如 /v1beta/models/{model}:generateContent，直接调用 Gemini 模型。
• 支持实时流式响应，适合交互式对话或长文本生成。
• 支持多模态输入，处理文本和图像等混合内容。
• 提供 Google 搜索增强功能，通过 -search 模型变体提供更准确的响应。
• 支持控制 Gemini 的推理过程，使用 -nothinking 和 -maxthinking 模型变体调整推理深度。
• 支持多种认证方式，包括 Bearer 令牌、Basic 认证、API 密钥等。
• 支持 Docker 容器化部署，兼容 Hugging Face Spaces。

使用帮助

安装流程

geminicli2api 的安装和配置简单，支持本地运行和容器化部署。以下是详细步骤：

1. 克隆仓库
   使用以下命令克隆 geminicli2api 仓库到本地：

   git clone https://github.com/gzzhongqi/geminicli2api
   cd geminicli2api
   

2. 安装依赖
   项目基于 Python 和 FastAPI 开发，依赖列在 requirements.txt 中。运行以下命令安装：

   pip install -r requirements.txt
   

3. 配置环境变量
   geminicli2api 需配置认证相关环境变量。创建一个 .env 文件，添加以下内容：

   GEMINI_AUTH_PASSWORD=你的认证密码
   GEMINI_CREDENTIALS={"client_id":"你的客户端ID","client_secret":"你的客户端密钥","token":"你的访问令牌","refresh_token":"你的刷新令牌","scopes":["https://www.googleapis.com/auth/cloud-platform"],"token_uri":"https://oauth2.googleapis.com/token"}
   PORT=8888
   

   • GEMINI_AUTH_PASSWORD：API 访问的认证密码，必填。
   • GEMINI_CREDENTIALS：Google OAuth 凭据的 JSON 字符串，包含 client_id、client_secret 等字段。
   • 可选变量：
     • GOOGLE_APPLICATION_CREDENTIALS：Google OAuth 凭据文件路径。
     • GOOGLE_CLOUD_PROJECT 或 GEMINI_PROJECT_ID：Google Cloud 项目 ID。
   • 如果使用凭据文件，创建 credentials 目录，放入 Google Cloud 服务账户的 .json 文件，并设置 GOOGLE_APPLICATION_CREDENTIALS 指向文件路径。
4. 本地运行
   配置完成后，运行以下命令启动服务：

   python -m uvicorn app.main:app --host 0.0.0.0 --port 8888
   

   服务默认监听 http://localhost:8888。

5. Docker 部署
   geminicli2api 支持 Docker 容器化部署，简化环境配置。
   • 构建镜像：

     docker build -t geminicli2api .
     

   • 运行容器（默认端口 8888）：

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

   • 使用 Docker Compose：

     docker-compose up -d
     

     对于 Hugging Face Spaces 部署，使用端口 7860：

     docker-compose --profile hf up -d geminicli2api-hf
     

6. Hugging Face Spaces 部署
   • 登录 Hugging Face，创建新的 Docker Space。
   • 将仓库内容上传至 Space。
   • 在 Space 设置中添加环境变量：GEMINI_AUTH_PASSWORD 和 GEMINI_CREDENTIALS（或其他凭据来源）。
   • Space 将自动构建并部署服务，监听 http://<space-url>:7860。

使用 API

geminicli2api 提供 OpenAI 兼容和原生 Gemini API 端点，开发者可根据需求选择。

OpenAI 兼容 API

使用 OpenAI 客户端库调用 geminicli2api，端点与 OpenAI API 一致。
示例（Python）：

import openai
client = openai.OpenAI(
base_url="http://localhost:8888/v1",
api_key="your_password"  # GEMINI_AUTH_PASSWORD
)
response = client.chat.completions.create(
model="gemini-2.5-pro-maxthinking",
messages=[{"role": "user", "content": "用简单语言解释相对论"}],
stream=True
)
for chunk in response:
if chunk.choices[0].delta.reasoning_content:
print(f"推理过程: {chunk.choices[0].delta.reasoning_content}")
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")

原生 Gemini API

直接调用 Gemini API 端点，支持更灵活的配置。
示例（Python）：

import requests
headers = {
"Authorization": "Bearer your_password",
"Content-Type": "application/json"
}
data = {
"contents": [
{"role": "user", "parts": [{"text": "用简单语言解释相对论"}]}
],
"thinkingConfig": {"thinkingBudget": 32768, "includeThoughts": True}
}
response = requests.post(
"http://localhost:8888/v1beta/models/gemini-2.5-pro:generateContent",
headers=headers,
json=data
)
print(response.json())

多模态输入

支持上传文本和图像，发送至 /v1/chat/completions 或 /v1beta/models/{model}:generateContent。
示例（上传图像和文本）：

curl -X POST http://localhost:8888/v1/chat/completions \
-H "Authorization: Bearer your_password" \
-H "Content-Type: application/json" \
-d '{"model": "gemini-2.5-pro", "messages": [{"role": "user", "content": "分析这张图片并描述内容"}], "files": ["./image.jpg"]}'

认证方式

支持以下认证方式：

• Bearer 令牌：Authorization: Bearer your_password
• Basic 认证：Authorization: Basic base64(username:your_password)
• 查询参数：?key=your_password
• Google 头部：x-goog-api-key: your_password

支持的模型

• 基础模型：gemini-2.5-pro、gemini-2.5-flash、gemini-1.5-pro、gemini-1.5-flash、gemini-1.0-pro
• 变体：
  • -search：启用 Google 搜索增强（如 gemini-2.5-pro-search）。
  • -nothinking：减少推理步骤（如 gemini-2.5-flash-nothinking）。
  • -maxthinking：增加推理预算（如 gemini-2.5-pro-maxthinking）。

注意事项

• 确保 GEMINI_AUTH_PASSWORD 已设置，否则 API 请求将失败。
• Google OAuth 凭据需有效，推荐从 Google Cloud 控制台获取。
• 流式响应需客户端支持分块数据处理。
• 检查 Google Cloud 项目配额，避免超过 API 调用限制。

应用场景

1. 集成现有 OpenAI 工具
   开发者使用 geminicli2api 将 Gemini 模型接入基于 OpenAI API 的工具（如 LangChain），无需修改代码，快速切换到 Gemini 的免费配额。
2. 多模态内容生成
   内容创作者上传图像和文本，生成描述、分析或创意内容，适合广告设计或教育素材制作。
3. 自动化工作流
   企业通过 geminicli2api 自动化处理文档、生成报告或回答客户查询，提升运营效率。

QA

1. geminicli2api 支持哪些认证方式？
   支持 Bearer 令牌、Basic 认证、查询参数和 Google 头部认证，需设置 GEMINI_AUTH_PASSWORD。
2. 如何获取 Google OAuth 凭据？
   在 Google Cloud 控制台创建服务账户，下载 JSON 密钥文件，填入 GEMINI_CREDENTIALS 或设置 GOOGLE_APPLICATION_CREDENTIALS 路径。
3. 支持哪些模型变体？
   支持 -search（Google 搜索增强）、-nothinking（减少推理）、-maxthinking（增加推理）变体，适用于 gemini-2.5-pro 和 gemini-2.5-flash。
4. 如何在 Hugging Face Spaces 部署？
   Fork 仓库，创建 Docker Space，设置 GEMINI_AUTH_PASSWORD 和 GEMINI_CREDENTIALS，Space 将自动部署。