---

title: Gemini CLI 到 API 代理 emoji: 🤖 colorFrom: blue colorTo: purple sdk: docker pinned: false license: mit app_port: 7860

Gemini CLI 到 API 代理 (geminicli2api)

一个基于 FastAPI 的代理服务器，可将 Gemini CLI 工具转换为兼容 OpenAI 的接口以及原生的 Gemini API 接口。这使您能够通过熟悉的 OpenAI API 接口或直接调用 Gemini API，来利用 Google 提供的免费 Gemini API 配额。

🚀 功能

• 兼容 OpenAI 的 API：可无缝替代 OpenAI 的聊天完成 API。
• 原生 Gemini API：直接代理 Google 的 Gemini API。
• 流式支持：两种 API 格式均支持实时流式响应。
• 多模态支持：支持文本和图像输入。
• 认证方式：多种认证方法（Bearer、Basic、API 密钥）。
• Google 搜索增强：启用 -search 模型以实现基于 Google 搜索的增强响应。
• 思考/推理控制：通过 -nothinking 和 -maxthinking 模型控制 Gemini 的思考过程。
• Docker 支持：容器化部署，方便快捷。
• Hugging Face Spaces：可直接部署到 Hugging Face 平台。

🔧 环境变量

必需

• GEMINI_AUTH_PASSWORD：用于 API 访问的认证密码。

可选凭证来源（任选其一）

• GEMINI_CREDENTIALS：包含 Google OAuth 凭证的 JSON 字符串。
• GOOGLE_APPLICATION_CREDENTIALS：Google OAuth 凭证文件的路径。
• GOOGLE_CLOUD_PROJECT：Google Cloud 项目 ID。
• GEMINI_PROJECT_ID：备用项目 ID 变量。

凭证 JSON 示例

{
  "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"
}

📡 API 端点

兰兼容 OpenAI 的端点

• POST /v1/chat/completions - 聊天完成（流式与非流式）
• GET /v1/models - 列出可用模型

原生 Gemini 端点

• GET /v1beta/models - 列出 Gemini 模型
• POST /v1beta/models/{model}:generateContent - 生成内容
• POST /v1beta/models/{model}:streamGenerateContent - 流式生成内容
• 所有其他 Gemini API 端点均被代理转发。

实用端点

• GET /health - 用于容器编排的健康检查

🔐 认证

API 支持多种认证方式：

1. Bearer Token：Authorization: Bearer YOUR_PASSWORD
2. Basic Auth：Authorization: Basic base64(username:YOUR_PASSWORD)
3. 查询参数：?key=YOUR_PASSWORD
4. Google Header：x-goog-api-key: YOUR_PASSWORD

🐳 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

# 在端口 7860 上运行（兼容 Hugging Face）
docker run -p 7860:7860 \
  -e GEMINI_AUTH_PASSWORD=your_password \
  -e GEMINI_CREDENTIALS='{"client_id":"...","token":"..."}' \
  -e PORT=7860 \
  geminicli2api

Docker Compose

# 默认设置（端口 8888）
docker-compose up -d

# Hugging Face 设置（端口 7860）
docker-compose --profile hf up -d geminicli2api-hf

🤗 Hugging Face Spaces

本项目已配置为可在 Hugging Face Spaces 上部署：

1. 分叉此仓库。
2. 在 Hugging Face 上创建一个新的 Space。
3. 连接您的仓库。
4. 在 Space 设置中配置所需的环境变量：
   • GEMINI_AUTH_PASSWORD
   • GEMINI_CREDENTIALS（或其他凭证来源）。

Space 将自动使用包含的 Dockerfile 进行构建和部署。

📝 OpenAI API 示例

import openai

# 配置客户端以使用您的代理
client = openai.OpenAI(
    base_url="http://localhost:8888/v1",  # 或 7860 用于 HF
    api_key="your_password"  # 您的 GEMINI_AUTH_PASSWORD
)

# 像使用普通 OpenAI API 一样使用
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 示例

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",  # 或 7860 用于 HF
    headers=headers,
    json=data
)

print(response.json())

🎯 支持的模型

基础模型

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

模型变体

代理会自动为 gemini-2.5-pro 和 gemini-2.5-flash 模型创建变体：

• -search：在模型名称后添加 -search 以启用 Google 搜索增强。
  • 示例：gemini-2.5-pro-search
• -nothinking：在模型名称后添加 -nothinking 以减少推理步骤。
  • 示例：gemini-2.5-flash-nothinking
• -maxthinking：在模型名称后添加 -maxthinking 以最大化推理预算。
  • 示例：gemini-2.5-pro-maxthinking

📄 许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

geminicli2api 快速上手指南

geminicli2api 是一个基于 FastAPI 的代理服务器，能将 Google Gemini CLI 工具转换为 OpenAI 兼容接口或原生 Gemini API 端点。通过它，你可以利用免费的 Gemini API 额度，并使用熟悉的 OpenAI 客户端库进行开发。

环境准备

• 操作系统：Linux、macOS 或 Windows（需安装 Docker）
• 前置依赖：
  • Docker 和 docker-compose（推荐 v2+）
  • Google Cloud 凭证（OAuth JSON 或服务账号密钥），用于访问 Gemini API
• 网络要求：确保容器能访问 googleapis.com（国内用户可能需要配置代理或使用加速节点）

安装步骤

1. 获取源码

git clone https://github.com/your-repo/geminicli2api.git
cd geminicli2api

2. 准备认证信息

你需要准备 Google OAuth 凭证 JSON 字符串。将其保存为环境变量或直接填入启动命令。 示例凭证结构：

{
  "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"
}

3. 使用 Docker 启动服务

你可以根据需求选择端口（默认 8888 或 Hugging Face 兼容的 7860）。

方式 A：直接运行 Docker 命令

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

注意：请将 GEMINI_CREDENTIALS 的值替换为你实际的 JSON 字符串（需转义引号），并将 my_secure_password 替换为你设定的访问密码。

方式 B：使用 Docker Compose

# 默认配置 (端口 8888)
docker-compose up -d

# 或者 Hugging Face 配置 (端口 7860)
docker-compose --profile hf up -d geminicli2api-hf

提示：使用前请编辑 docker-compose.yml 或在同目录下创建 .env 文件来配置 GEMINI_AUTH_PASSWORD 和 GEMINI_CREDENTIALS。

基本使用

启动成功后，服务将监听指定端口。你可以选择 OpenAI 兼容模式 或 原生 Gemini 模式。

模式一：OpenAI 兼容接口（推荐）

适用于已集成 OpenAI SDK 的项目，只需修改 base_url 和 api_key。

import openai

# 初始化客户端
client = openai.OpenAI(
    base_url="http://localhost:8888/v1",  # 若使用 HF 部署则改为 7860
    api_key="my_secure_password"          # 对应 GEMINI_AUTH_PASSWORD
)

# 调用对话接口
response = client.chat.completions.create(
    model="gemini-2.5-pro-maxthinking",   # 支持 -search, -nothinking 等后缀
    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="", flush=True)

模式二：原生 Gemini 接口

直接通过 HTTP 请求调用 Gemini 原生格式。

import requests

headers = {
    "Authorization": "Bearer my_secure_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())

常用模型变体

在模型名称后添加后缀即可启用特殊功能：

• 联网搜索：gemini-2.5-pro-search
• 关闭深度思考：gemini-2.5-flash-nothinking
• 最大深度思考：gemini-2.5-pro-maxthinking