Gemini-FastAPI

[ English | 中文 ]

基于Web的Gemini模型，封装成与OpenAI兼容的API。由HanaokaYuzu/Gemini-API提供支持。

✅ 无需API密钥即可通过API调用Gemini的Web模型，完全免费！

特性

• 🔐 无需Google API密钥：使用Web Cookie即可免费通过API访问Gemini模型。
• 🔍 内置Google搜索：利用Gemini的网络搜索能力获取最新答案。
• 💾 对话持久化：基于LMDB的存储，支持多轮对话。
• 🖼️ 多模态支持：支持文本、图片及文件上传。
• ⚖️ 多账号负载均衡：可通过每个账号的代理设置，将请求分发到多个账号。

快速开始

关于Docker部署，请参阅下方的[Docker部署]部分。

前提条件

• Python 3.13
• 拥有Gemini网页版访问权限的Google账号
• 来自Gemini网页界面的secure_1psid和secure_1psidts Cookie

安装

使用uv（推荐）

git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
uv sync

使用pip

git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
pip install -e .

配置

编辑config/config.yaml文件，并至少提供一组凭证：

gemini:
  clients:
    - id: "client-a"
      secure_1psid: "YOUR_SECURE_1PSID_HERE"
      secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE"
      proxy: null # 可选代理URL（null/空则保持直连）

[!NOTE] 更多详情请参阅下方的[配置]部分。

启动服务器

# 使用uv
uv run python run.py

# 直接使用Python
python run.py

服务器默认将在http://localhost:8000启动。

API端点

服务器提供了多个端点，其中包括与OpenAI兼容的端点。

OpenAI兼容端点

这些端点设计为与OpenAI的API结构兼容，允许您将Gemini作为直接替代品使用。

• GET /v1/models：列出所有支持的Gemini模型。
• POST /v1/chat/completions：统一的聊天接口。
  • 流式传输：设置stream: true以实时接收增量内容。
  • 多模态：支持文本、图片和文件上传。
  • 工具调用：通过tools参数支持函数调用。
  • 结构化输出：支持response_format以强制执行JSON模式。

高级端点

• POST /v1/responses：用于复杂交互模式的替代端点，支持丰富的输出内容，包括生成的图片和工具调用。

工具端点

• GET /health：健康检查端点。返回服务器状态、已配置的Gemini客户端以及对话存储情况。
• GET /images/{filename}：用于服务生成图片的内部端点。需要有效的令牌（自动包含在API返回的图片URL中）。

Docker部署

带选项运行

docker run -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/cache:/app/cache \
  -e CONFIG_SERVER__API_KEY="your-api-key-here" \
  -e CONFIG_GEMINI__CLIENTS__0__ID="client-a" \
  -e CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID="your-secure-1psid" \
  -e CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="your-secure-1psidts" \
  -e GEMINI_COOKIE_PATH="/app/cache" \
  ghcr.io/nativu5/gemini-fastapi

[!TIP] 仅当需要代理时才添加CONFIG_GEMINI__CLIENTS__N__PROXY；省略该变量则保持直连。

GEMINI_COOKIE_PATH指向容器内存储刷新后Cookie的目录。将其绑定挂载（例如-v $(pwd)/cache:/app/cache）可在容器重建或重新创建时保留这些Cookie，从而减少重新认证的需求。

使用Docker Compose运行

创建一个docker-compose.yml文件：

services:
  gemini-fastapi:
    image: ghcr.io/nativu5/gemini-fastapi:latest
    ports:
      - "8000:8000"
    volumes:
      # - ./config:/app/config      # 如需使用自定义配置文件，请取消注释
      # - ./certs:/app/certs        # 如需启用HTTPS并使用您的证书，请取消注释
      - ./data:/app/data
      - ./cache:/app/cache
    environment:
      - CONFIG_SERVER__HOST=0.0.0.0
      - CONFIG_SERVER__PORT=8000
      - CONFIG_SERVER__API_KEY=${API_KEY}
      - CONFIG_GEMINI__CLIENTS__0__ID=client-a
      - CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID=${SECURE_1PSID}
      - CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS=${SECURE_1PSIDTS}
      - GEMINI_COOKIE_PATH=/app/cache # 必须与上述缓存卷挂载一致
    restart: on-failure:3 # 避免过多重试

然后运行：

docker compose up -d

[!IMPORTANT] 务必挂载/app/data卷，以在容器重启时持久化对话数据。 同时挂载/app/cache，以便刷新后的Cookie（包括轮换的1PSIDTS值）能够在容器重建或重新创建时保留，而无需再次认证。

配置

服务器会读取位于config/config.yaml的YAML配置文件。

有关每个配置选项的详细信息，请参阅config/config.yaml文件中的注释。

环境变量覆盖

[!TIP] 此功能对于Docker部署和生产环境特别有用，在这些环境中您希望将敏感凭据与配置文件分开存放。

您可以使用带有CONFIG_前缀的环境变量来覆盖任何配置选项。使用双下划线(__)表示嵌套键，例如：

# 覆盖服务器设置
export CONFIG_SERVER__API_KEY="your-secure-api-key"

# 覆盖Gemini客户端0的凭据
export CONFIG_GEMINI__CLIENTS__0__ID="client-a"
export CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID="your-secure-1psid"
export CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="your-secure-1psidts"

# 覆盖客户端0的可选代理设置
export CONFIG_GEMINI__CLIENTS__0__PROXY="socks5://127.0.0.1:1080"

# 覆盖对话存储大小限制
export CONFIG_STORAGE__MAX_SIZE=268435456  # 256 MB

客户端ID与对话复用

对话会根据生成它们的客户端ID进行存储。 请在配置中保持这些标识符稳定，以便在更新Cookie列表时会话仍能有效。

Gemini 凭证

[!WARNING] 请妥善保管这些凭证，切勿将其提交到版本控制系统中。这些 Cookie 可用于访问您的 Google 帐户。

要使用 Gemini-FastAPI，您需要提取 Gemini 会话的 Cookie：

1. 在浏览器的隐私/无痕窗口中打开 Gemini 并登录。
2. 打开开发者工具（F12）。
3. 导航至 Application → Storage → Cookies。
4. 找到并复制以下值：
   • __Secure-1PSID
   • __Secure-1PSIDTS

[!TIP] 如需详细说明，请参阅 HanaokaYuzu/Gemini-API 身份验证指南。

代理设置

每个客户端条目都可以配置不同的代理，以绕过速率限制。如果省略 proxy 字段，或将该字段设置为 null 或空字符串，则保持直接连接。

聊天会话模式

您可以控制请求是使用常规 Google 聊天，还是使用 Google 的临时聊天模式：

gemini:
  chat_mode: "normal" # "normal"（复用元数据）或 "temporary"（Google 临时聊天，不会保存到帐户）
  max_chars_per_request: 1000000
  oversized_context_strategy: "compaction" # "compaction" 或 "file"

当 chat_mode 设置为 temporary 时，服务器会应用一个内部有效输入限制，即 max_chars_per_request 的 90%。当上下文超出有效预算时，处理方式由 oversized_context_strategy 控制：

• compaction：总结较早的对话轮次，并原样保留最近的对话轮次。
• file：将过大的上下文作为 message.txt 文件附加，并从文件中进行处理。

环境变量等效项：

export CONFIG_GEMINI__CHAT_MODE="temporary"
export CONFIG_GEMINI__MAX_CHARS_PER_REQUEST=1000000
export CONFIG_GEMINI__OVERSIZED_CONTEXT_STRATEGY="compaction"

自定义模型

您可以在 config/config.yaml 中或通过环境变量定义自定义模型。

YAML 配置

gemini:
  model_strategy: "append" # "append"（默认 + 自定义）或 "overwrite"（仅自定义）
  models:
    - model_name: "gemini-3.0-pro"
      model_header:
        x-goog-ext-525001261-jspb: '[1,null,null,null,"9d8ca3786ebdfbea",null,null,0,[4],null,null,1]'

环境变量

您可以通过 CONFIG_GEMINI__MODELS 以 JSON 字符串或列表结构提供模型。这种方式提供了灵活的方法，允许通过 Shell 或自动化环境（例如 Docker）覆盖设置，而无需修改配置文件。

export CONFIG_GEMINI__MODEL_STRATEGY="overwrite"
export CONFIG_GEMINI__MODELS='[{"model_name": "gemini-3.0-pro", "model_header": {"x-goog-ext-525001261-jspb": "[1,null,null,null,\"9d8ca3786ebdfbea\",null,null,0,[4],null,null,1]"}}]'

致谢

• HanaokaYuzu/Gemini-API - 底层的 Gemini Web API 客户端。
• zhiyu1998/Gemi2Api-Server - 本项目最初源自该仓库。经过大量重构和工程改进后，它已发展成为一个独立项目，具备多轮对话复用等增强功能。特别感谢其提供的灵感和基础工作。

免责声明

本项目与 Google 或 OpenAI 无关，仅用于教育和研究目的。该项目使用逆向工程的 API，可能不符合 Google 的服务条款。请自行承担使用风险。

Gemini-FastAPI 快速上手指南

Gemini-FastAPI 是一个将 Google Gemini 网页版模型封装为 OpenAI 兼容 API 的工具。无需 Google API Key，通过提取浏览器 Cookie 即可免费调用 Gemini 模型，支持多模态、联网搜索及多轮对话持久化。

环境准备

在开始之前，请确保满足以下条件：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.13 或更高版本
• Google 账号：拥有访问 gemini.google.com 权限的账号
• 关键凭证：需要从浏览器获取以下两个 Cookie 值：
  • __Secure-1PSID
  • __Secure-1PSIDTS

如何获取 Cookie：

1. 使用浏览器的无痕/隐私模式登录 Gemini。
2. 按 F12 打开开发者工具，进入 Application (应用) > Storage (存储) > Cookies。
3. 找到并复制上述两个字段的值。

安装步骤

推荐使用 uv 进行安装（速度更快），也可以使用 pip。

方式一：使用 uv（推荐）

git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
uv sync

方式二：使用 pip

git clone https://github.com/Nativu5/Gemini-FastAPI.git
cd Gemini-FastAPI
pip install -e .

基本使用

1. 配置凭证

编辑项目根目录下的 config/config.yaml 文件，填入你获取到的 Cookie 信息：

gemini:
  clients:
    - id: "client-a"
      secure_1psid: "YOUR_SECURE_1PSID_HERE"
      secure_1psidts: "YOUR_SECURE_1PSIDTS_HERE"
      proxy: null # 如需代理可填写，否则保持 null

2. 启动服务

在项目目录下运行以下命令启动服务器：

# 如果使用 uv 安装
uv run python run.py

# 如果使用 pip 安装
python run.py

默认情况下，服务将在 http://localhost:8000 启动。

3. 调用示例

该服务完全兼容 OpenAI API 格式。你可以使用任何支持 OpenAI 协议的客户端（如 openai Python 库、NextChat、LobeChat 等）进行连接。

Python 调用示例：

from openai import OpenAI

# 初始化客户端，base_url 指向本地服务，api_key 可随意填写（除非在配置中设置了特定 key）
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed" 
)

response = client.chat.completions.create(
    model="gemini-2.0-flash-exp", # 或其他支持的模型名称
    messages=[
        {"role": "system", "content": "你是一个有用的助手。"},
        {"role": "user", "content": "你好，请介绍一下你自己。"}
    ],
    stream=True # 支持流式输出
)

for chunk in response:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="", flush=True)

Docker 快速部署（可选）：

如果你更倾向于使用 Docker，可以直接运行：

docker run -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/cache:/app/cache \
  -e CONFIG_GEMINI__CLIENTS__0__ID="client-a" \
  -e CONFIG_GEMINI__CLIENTS__0__SECURE_1PSID="YOUR_SECURE_1PSID" \
  -e CONFIG_GEMINI__CLIENTS__0__SECURE_1PSIDTS="YOUR_SECURE_1PSIDTS" \
  ghcr.io/nativu5/gemini-fastapi

注意：请确保挂载 ./cache 目录以持久化 Cookie，避免容器重启后需要重新认证。