## File: README.md

# GeminiCLI to API

**将 GeminiCLI 和 Antigravity 转换为 OpenAI 、GEMINI 和 Claude API 兼容接口**

[](https://www.python.org/downloads/)
[](LICENSE)
[](https://github.com/su-kaka/gcli2api/pkgs/container/gcli2api)

[English](docs/README_EN.md) | 中文 | [日本語](docs/README_JA.md)

## 🚀 快速部署 

[](https://zeabur.com/templates/97VMEF?referralCode=sukaka)
[](https://render.com/deploy?repo=https://github.com/su-kaka/gcli2api)
---

## 安装指南

### Termux 环境

**初始安装**
```bash
curl -o termux-install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/termux-install.sh" && chmod +x termux-install.sh && ./termux-install.sh
```

**重启服务**
```bash
cd gcli2api
bash termux-start.sh
```

### Windows 环境

**初始安装**
```powershell
iex (iwr "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/install.ps1" -UseBasicParsing).Content
```

**重启服务**
双击执行 `start.bat`

### Linux 环境

**初始安装**
```bash
curl -o install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/install.sh" && chmod +x install.sh && ./install.sh
```

**重启服务**
```bash
cd gcli2api
bash start.sh
```

### macOS 环境

**初始安装**
```bash
curl -o darwin-install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/darwin-install.sh" && chmod +x darwin-install.sh && ./darwin-install.sh
```

**重启服务**
```bash
cd gcli2api
bash start.sh
```

### Docker 环境

**Docker 运行命令**
```bash
# 使用通用密码
docker run -d --name gcli2api --network host -e PASSWORD=pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds ghcr.io/su-kaka/gcli2api:latest

# 使用分离密码
docker run -d --name gcli2api --network host -e API_PASSWORD=api_pwd -e PANEL_PASSWORD=panel_pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds ghcr.io/su-kaka/gcli2api:latest
```

**Docker Mac**
```bash
# 使用通用密码
docker run -d \
  --name gcli2api \
  -p 7861:7861 \
  -p 8080:8080 \
  -e PASSWORD=pwd \
  -e PORT=7861 \
  -v "$(pwd)/data/creds":/app/creds \
  ghcr.io/su-kaka/gcli2api:latest
```

```bash
# 使用分离密码
docker run -d \
--name gcli2api \
-p 7861:7861 \
-p 8080:8080 \
-e API_PASSWORD=api_pwd \
-e PANEL_PASSWORD=panel_pwd \
-e PORT=7861 \
-v $(pwd)/data/creds:/app/creds \
ghcr.io/su-kaka/gcli2api:latest
```

**Docker Compose 运行命令**
1. 将以下内容保存为 `docker-compose.yml` 文件：
    ```yaml
    version: '3.8'

    services:
      gcli2api:
        image: ghcr.io/su-kaka/gcli2api:latest
        container_name: gcli2api
        restart: unless-stopped
        network_mode: host
        environment:
          # 使用通用密码（推荐用于简单部署）
          - PASSWORD=pwd
          - PORT=7861
          # 或使用分离密码（推荐用于生产环境）
          # - API_PASSWORD=your_api_password
          # - PANEL_PASSWORD=your_panel_password
        volumes:
          - ./data/creds:/app/creds
        healthcheck:
          test: ["CMD-SHELL", "python -c \"import sys, urllib.request, os; port = os.environ.get('PORT', '7861'); req = urllib.request.Request(f'http://localhost:{port}/v1/models', headers={'Authorization': 'Bearer ' + os.environ.get('PASSWORD', 'pwd')}); sys.exit(0 if urllib.request.urlopen(req, timeout=5).getcode() == 200 else 1)\""]
          interval: 30s
          timeout: 10s
          retries: 3
          start_period: 40s
    ```
2. 启动服务：
    ```bash
    docker-compose up -d
    ```

## 核心功能

### 🔄 API 端点和格式支持

**多端点多格式支持**
- **OpenAI 兼容端点**：`/v1/chat/completions` 和 `/v1/models`
  - 支持标准 OpenAI 格式（messages 结构）
  - 支持 Gemini 原生格式（contents 结构）
  - 自动格式检测和转换，无需手动切换
  - 支持多模态输入（文本 + 图像）
- **Gemini 原生端点**：`/v1/models/{model}:generateContent` 和 `streamGenerateContent`
  - 支持完整的 Gemini 原生 API 规范
  - 多种认证方式：Bearer Token、x-goog-api-key 头部、URL 参数 key
- **Claude 格式兼容**：完整支持 Claude API 格式
  - 端点：`/v1/messages`（遵循 Claude API 规范）
  - 支持 Claude 标准的 messages 格式
  - 支持 system 参数和 Claude 特有功能
  - 自动转换为后端支持的格式
- **Antigravity API 支持**：同时支持 OpenAI、Gemini 和 Claude 格式
  - OpenAI 格式端点：`/antigravity/v1/chat/completions`
  - Gemini 格式端点：`/antigravity/v1/models/{model}:generateContent` 和 `streamGenerateContent`
  - Claude 格式端点：`/antigravity/v1/messages`
  - 支持所有 Antigravity 模型（Claude、Gemini 等）
  - 自动模型名称映射和思维模式检测

### 🔐 认证和安全管理

**灵活的密码管理**
- **分离密码支持**：API 密码（聊天端点）和控制面板密码可独立设置
- **多种认证方式**：支持 Authorization Bearer、x-goog-api-key 头部、URL 参数等
- **JWT Token 认证**：控制面板支持 JWT 令牌认证
- **用户邮箱获取**：自动获取和显示 Google 账户邮箱地址

### 📊 智能凭证管理系统

**高级凭证管理**
- 多个 Google OAuth 凭证自动轮换
- 通过冗余认证增强稳定性
- 负载均衡与并发请求支持
- 自动故障检测和凭证禁用
- 凭证使用统计和配额管理
- 支持手动启用/禁用凭证文件
- 批量凭证文件操作（启用、禁用、删除）

**凭证状态监控**
- 实时凭证健康检查
- 错误码追踪（429、403、500 等）
- 自动封禁机制（可配置）

### 🌊 流式传输和响应处理

**多种流式支持**
- 真正的实时流式响应
- 假流式模式（用于兼容性）
- 流式抗截断功能（防止回答被截断）
- 异步任务管理和超时处理

**响应优化**
- 思维链（Thinking）内容分离
- 推理过程（reasoning_content）处理
- 多轮对话上下文管理
- 兼容性模式（将 system 消息转换为 user 消息）

### 🎛️ Web 管理控制台

**全功能 Web 界面**
- OAuth 认证流程管理（支持 GCLI 和 Antigravity 双模式）
- 凭证文件上传、下载、管理
- 实时日志查看（WebSocket）
- 系统配置管理
- 使用统计和监控面板
- 移动端适配界面

**批量操作支持**
- ZIP 文件批量上传凭证（GCLI 和 Antigravity）
- 批量启用/禁用/删除凭证
- 批量获取用户邮箱
- 批量配置管理
- 统一批量上传界面管理所有凭证类型

### 📈 使用监控

**实时监控**
- WebSocket 实时日志流
- 系统状态监控
- 凭证健康状态

### 🔧 高级配置和自定义

**网络和代理配置**
- HTTP/HTTPS 代理支持
- 代理端点配置（OAuth、Google APIs、元数据服务）
- 超时和重试配置
- 网络错误处理和恢复

**性能和稳定性配置**
- 429 错误自动重试（可配置间隔和次数）
- 抗截断最大重试次数

**日志和调试**
- 多级日志系统（DEBUG、INFO、WARNING、ERROR）
- 日志文件管理
- 实时日志流
- 日志下载和清空

### 🔄 环境变量和配置管理

**灵活的配置方式**
- 环境变量配置
- 热配置更新（部分配置项）
- 配置锁定（环境变量优先级）

## 支持的模型

所有模型均具备 1M 上下文窗口容量。每个凭证文件提供 1000 次请求额度。

### 🤖 基础模型
- `gemini-2.5-pro`
- `gemini-3-pro-preview`
- `gemini-3.1-pro-preview`

### 🧠 思维模型（Thinking Models）
- `gemini-2.5-pro-high`：思考模式
- `gemini-2.5-pro-low`：低思考模式
- 支持自定义思考预算配置
- 自动分离思维内容和最终回答

### 🔍 搜索增强模型
- `gemini-2.5-pro-search`：集成搜索功能的模型

### 🖼️ 图像生成模型（Antigravity）
- `gemini-3.1-flash-image`：基础图像生成模型
- **分辨率后缀**：
  - `-2k`：2K 分辨率
  - `-4k`：4K 高清分辨率
- **比例后缀**：
  - `-1x1`：正方形（头像）
  - `-16x9`：横屏（电脑壁纸）
  - `-9x16`：竖屏（手机壁纸）
  - `-21x9`：超宽屏（带鱼屏）
  - `-4x3`：传统显示器
  - `-3x4`：竖版海报
- **组合使用示例**：
  - `gemini-3.1-flash-image-4k-16x9`：4K 横屏
  - `gemini-3.1-flash-image-2k-9x16`：2K 竖屏
- 不指定比例时，API 自动决定横竖比例

### 🌊 特殊功能变体
- **假流式模式**：在任何模型名称后添加 `-假流式` 后缀
  - 例：`gemini-2.5-pro-假流式`
  - 用于需要流式响应但服务端不支持真流式的场景
- **流式抗截断模式**：在模型名称前添加 `流式抗截断/` 前缀
  - 例：`流式抗截断/gemini-2.5-pro`  
  - 自动检测响应截断并重试，确保完整回答

### 🔧 模型功能自动检测
- 系统自动识别模型名称中的功能标识
- 透明地处理功能模式转换
- 支持功能组合使用

---

## 配置说明

1. 访问 `http://127.0.0.1:7861` （默认端口，可通过 PORT 环境变量修改）
2. 完成 OAuth 认证流程（默认密码：`pwd`，可通过环境变量修改）
   - **GCLI 模式**：用于获取 Google Cloud Gemini API 凭证
   - **Antigravity 模式**：用于获取 Google Antigravity API 凭证
3. 配置客户端：

**OpenAI 兼容客户端：**
   - **端点地址**：`http://127.0.0.1:7861/v1`
   - **API 密钥**：`pwd`（默认值，可通过 API_PASSWORD 或 PASSWORD 环境变量修改）

**Gemini 原生客户端：**
   - **端点地址**：`http://127.0.0.1:7861`
   - **认证方式**：
     - `Authorization: Bearer your_api_password`
     - `x-goog-api-key: your_api_password`
     - URL 参数：`?key=your_api_password`

### 🌟 双认证模式支持

**GCLI 认证模式**
- 标准的 Google Cloud Gemini API 认证
- 支持 OAuth2.0 认证流程
- 自动启用必需的 Google Cloud API

**Antigravity 认证模式**
- Google Antigravity API 专用认证
- 独立的凭证管理系统
- 支持批量上传和管理
- 与 GCLI 凭证完全隔离

**统一管理界面**
- 在"批量上传"标签页中可一次性管理两种凭证
- 上半部分：GCLI 凭证批量上传（蓝色主题）
- 下半部分：Antigravity 凭证批量上传（绿色主题）
- 各自独立的凭证管理标签页

## 💾 数据存储模式

### 🌟 存储后端支持

gcli2api 支持两种存储后端：**本地 SQLite（默认）** 和 **MongoDB（云端分布式存储）**

### 📁 本地 SQLite 存储（默认）

**默认存储方式**
- 无需配置，开箱即用
- 数据存储在本地 SQLite 数据库中
- 适合单机部署和个人使用
- 自动创建和管理数据库文件

### 🍃 MongoDB 云端存储模式

**云端分布式存储方案**

当需要多实例部署或云端存储时，可以启用 MongoDB 存储模式。

### ⚙️ 启用 MongoDB 模式

**步骤 1: 配置 MongoDB 连接**
```bash
# 本地 MongoDB
export MONGODB_URI="mongodb://localhost:27017"

# MongoDB Atlas 云服务
export MONGODB_URI="mongodb+srv://username:password@cluster.mongodb.net"

# 带认证的 MongoDB
export MONGODB_URI="mongodb://admin:password@localhost:27017/admin"

# 可选：自定义数据库名称（默认: gcli2api）
export MONGODB_DATABASE="my_gcli_db"
```

**步骤 2: 启动应用**
```bash
# 应用会自动检测 MongoDB 配置并使用 MongoDB 存储
python web.py
```

**Docker 环境使用 MongoDB**
```bash
# 单机 MongoDB 部署
docker run -d --name gcli2api \
  -e MONGODB_URI="mongodb://mongodb:27017" \
  -e API_PASSWORD=your_password \
  --network your_network \
  ghcr.io/su-kaka/gcli2api:latest

# 使用 MongoDB Atlas
docker run -d --name gcli2api \
  -e MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/gcli2api" \
  -e API_PASSWORD=your_password \
  -p 7861:7861 \
  ghcr.io/su-kaka/gcli2api:latest
```

**Docker Compose 示例**
```yaml
version: '3.8'

services:
  mongodb:
    image: mongo:7
    container_name: gcli2api-mongodb
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password123
    volumes:
      - mongodb_data:/data/db
    ports:
      - "27017:27017"

  gcli2api:
    image: ghcr.io/su-kaka/gcli2api:latest
    container_name: gcli2api
    restart: unless-stopped
    depends_on:
      - mongodb
    environment:
      - MONGODB_URI=mongodb://admin:password123@mongodb:27017/admin
      - MONGODB_DATABASE=gcli2api
      - API_PASSWORD=your_api_password
      - PORT=7861
    ports:
      - "7861:7861"

volumes:
  mongodb_data:
```


### 🔧 高级配置

**MongoDB 连接优化**
```bash
# 连接池和超时配置
export MONGODB_URI="mongodb://localhost:27017?maxPoolSize=10&serverSelectionTimeoutMS=5000"

# 副本集配置
export MONGODB_URI="mongodb://host1:27017,host2:27017,host3:27017/gcli2api?replicaSet=myReplicaSet"

# 读写分离配置
export MONGODB_URI="mongodb://localhost:27017/gcli2api?readPreference=secondaryPreferred"
```

### 环境变量配置

**基础配置**
- `PORT`: 服务端口（默认：7861）
- `HOST`: 服务器监听地址（默认：0.0.0.0）

**密码配置**
- `API_PASSWORD`: 聊天 API 访问密码（默认：继承 PASSWORD 或 pwd）
- `PANEL_PASSWORD`: 控制面板访问密码（默认：继承 PASSWORD 或 pwd）  
- `PASSWORD`: 通用密码，设置后覆盖上述两个（默认：pwd）

**性能和稳定性配置**
- `RETRY_429_ENABLED`: 启用 429 错误自动重试（默认：true）
- `RETRY_429_MAX_RETRIES`: 429 错误最大重试次数（默认：3）
- `RETRY_429_INTERVAL`: 429 错误重试间隔，秒（默认：1.0）
- `ANTI_TRUNCATION_MAX_ATTEMPTS`: 抗截断最大重试次数（默认：3）

**网络和代理配置**
- `PROXY`: HTTP/HTTPS 代理地址（格式：`http://host:port`）
- `OAUTH_PROXY_URL`: OAuth 认证代理端点
- `GOOGLEAPIS_PROXY_URL`: Google APIs 代理端点
- `METADATA_SERVICE_URL`: 元数据服务代理端点

**自动化配置**
- `AUTO_BAN`: 启用凭证自动封禁（默认：true）
- `AUTO_LOAD_ENV_CREDS`: 启动时自动加载环境变量凭证（默认：false）

**兼容性配置**
- `COMPATIBILITY_MODE`: 启用兼容性模式，将 system 消息转为 user 消息（默认：false）

**日志配置**
- `LOG_LEVEL`: 日志级别（DEBUG/INFO/WARNING/ERROR，默认：INFO）
- `LOG_FILE`: 日志文件路径（默认：log.txt）

**存储配置**

**SQLite 配置（默认）**
- 无需配置，自动使用本地 SQLite 数据库
- 数据库文件自动创建在项目目录

**MongoDB 配置（可选云端存储）**
- `MONGODB_URI`: MongoDB 连接字符串（设置后启用 MongoDB 模式）
- `MONGODB_DATABASE`: MongoDB 数据库名称（默认：gcli2api）

**Docker 使用示例**
```bash
# 使用通用密码
docker run -d --name gcli2api \
  -e PASSWORD=mypassword \
  -e PORT=7861 \
  ghcr.io/su-kaka/gcli2api:latest

# 使用分离密码
docker run -d --name gcli2api \
  -e API_PASSWORD=my_api_password \
  -e PANEL_PASSWORD=my_panel_password \
  -e PORT=7861 \
  ghcr.io/su-kaka/gcli2api:latest
```

注意：当设置了凭证环境变量时，系统将优先使用环境变量中的凭证，忽略 `creds` 目录中的文件。

### API 使用方式

本服务支持三套完整的 API 端点：

#### 1. OpenAI 兼容端点（GCLI）

**端点：** `/v1/chat/completions`
**认证：** `Authorization: Bearer your_api_password`

支持两种请求格式，会自动检测并处理：

**OpenAI 格式：**
```json
{
  "model": "gemini-2.5-pro",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "stream": true
}
```

**Gemini 原生格式：**
```json
{
  "model": "gemini-2.5-pro",
  "contents": [
    {"role": "user", "parts": [{"text": "Hello"}]}
  ],
  "systemInstruction": {"parts": [{"text": "You are a helpful assistant"}]},
  "generationConfig": {
    "temperature": 0.7
  }
}
```

#### 2. Gemini 原生端点（GCLI）

**非流式端点：** `/v1/models/{model}:generateContent`
**流式端点：** `/v1/models/{model}:streamGenerateContent`
**模型列表：** `/v1/models`

**认证方式（任选一种）：**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URL 参数：`?key=your_api_password`

**请求示例：**
```bash
# 使用 x-goog-api-key 头部
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'

# 使用 URL 参数
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-pro:streamGenerateContent?key=your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'
```

#### 3. Claude API 格式端点

**端点：** `/v1/messages`
**认证：** `x-api-key: your_api_password` 或 `Authorization: Bearer your_api_password`

**请求示例：**
```bash
curl -X POST "http://127.0.0.1:7861/v1/messages" \
  -H "x-api-key: your_api_password" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'
```

**支持 system 参数：**
```json
{
  "model": "gemini-2.5-pro",
  "max_tokens": 1024,
  "system": "You are a helpful assistant",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}
```

**说明：**
- 完全兼容 Claude API 格式规范
- 自动转换为 Gemini 格式调用后端
- 支持 Claude 的所有标准参数
- 响应格式符合 Claude API 规范

#### 4. Antigravity API 端点

**支持三种格式：OpenAI、Gemini 和 Claude**

##### Antigravity OpenAI 格式端点

**端点：** `/antigravity/v1/chat/completions`
**认证：** `Authorization: Bearer your_api_password`

**请求示例：**
```bash
curl -X POST "http://127.0.0.1:7861/antigravity/v1/chat/completions" \
  -H "Authorization: Bearer your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": true
  }'
```

##### Antigravity Gemini 格式端点

**非流式端点：** `/antigravity/v1/models/{model}:generateContent`
**流式端点：** `/antigravity/v1/models/{model}:streamGenerateContent`

**认证方式（任选一种）：**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URL 参数：`?key=your_api_password`

**请求示例：**
```bash
# Gemini 格式非流式请求
curl -X POST "http://127.0.0.1:7861/antigravity/v1/models/claude-sonnet-4-5:generateContent" \
  -H "x-goog-api-key: your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ],
    "generationConfig": {
      "temperature": 0.7
    }
  }'

# Gemini 格式流式请求
curl -X POST "http://127.0.0.1:7861/antigravity/v1/models/gemini-2.5-flash:streamGenerateContent?key=your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'
```

##### Antigravity Claude 格式端点

**端点：** `/antigravity/v1/messages`
**认证：** `x-api-key: your_api_password`

**请求示例：**
```bash
curl -X POST "http://127.0.0.1:7861/antigravity/v1/messages" \
  -H "x-api-key: your_api_password" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'
```

**支持的 Antigravity 模型：**
- Claude 系列：`claude-sonnet-4-5`、`claude-opus-4-5` 等
- Gemini 系列：`gemini-2.5-flash`、`gemini-2.5-pro` 等
- 自动支持思维模型（thinking models）

**Gemini 原生示例：**
```python
from io import BytesIO
from PIL import Image
from google.genai import Client
from google.genai.types import HttpOptions
from google.genai import types
# The client gets the API key from the environment variable `GEMINI_API_KEY`.

client = Client(
            api_key="pwd",
            http_options=HttpOptions(base_url="http://127.0.0.1:7861"),
        )

prompt = (
    """
    画一只猫
    """
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents=[prompt],
    config=types.GenerateContentConfig(
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
        )
    )
)
for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        image = Image.open(BytesIO(part.inline_data.data))
        image.save("generated_image.png")

```

**说明：**
- OpenAI 端点返回 OpenAI 兼容格式
- Gemini 端点返回 Gemini 原生格式
- 两种端点使用相同的 API 密码

## 📋 完整 API 参考

### Web 控制台 API

**认证端点**
- `POST /auth/login` - 用户登录
- `POST /auth/start` - 开始 OAuth 认证（支持 GCLI 和 Antigravity 模式）
- `POST /auth/callback` - 处理 OAuth 回调
- `POST /auth/callback-url` - 从回调 URL 直接完成认证
- `GET /auth/status/{project_id}` - 检查认证状态

**凭证管理端点**（支持 `mode=geminicli` 或 `mode=antigravity` 参数）
- `POST /creds/upload` - 批量上传凭证文件（支持 JSON 和 ZIP）
- `GET /creds/status` - 获取凭证状态列表（支持分页和筛选）
- `GET /creds/detail/{filename}` - 获取单个凭证详情
- `POST /creds/action` - 单个凭证操作（启用/禁用/删除）
- `POST /creds/batch-action` - 批量凭证操作
- `GET /creds/download/{filename}` - 下载单个凭证文件
- `GET /creds/download-all` - 打包下载所有凭证
- `POST /creds/fetch-email/{filename}` - 获取用户邮箱
- `POST /creds/refresh-all-emails` - 批量刷新用户邮箱
- `POST /creds/deduplicate-by-email` - 按邮箱去重凭证
- `POST /creds/verify-project/{filename}` - 检验凭证 Project ID
- `GET /creds/quota/{filename}` - 获取凭证额度信息（仅 Antigravity）

**配置管理端点**
- `GET /config/get` - 获取当前配置
- `POST /config/save` - 保存配置

**日志管理端点**
- `POST /logs/clear` - 清空日志
- `GET /logs/download` - 下载日志文件
- `WebSocket /logs/stream` - 实时日志流

**版本信息端点**
- `GET /version/info` - 获取版本信息（可选 `check_update=true` 参数检查更新）

### 聊天 API 功能特性

**多模态支持**
```json
{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "描述这张图片"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA..."
          }
        }
      ]
    }
  ]
}
```

**思维模式支持**
```json
{
  "model": "gemini-2.5-pro-maxthinking",
  "messages": [
    {"role": "user", "content": "复杂数学问题"}
  ]
}
```

响应将包含分离的思维内容：
```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "最终答案",
      "reasoning_content": "详细的思考过程..."
    }
  }]
}
```

**流式抗截断使用**
```json
{
  "model": "流式抗截断/gemini-2.5-pro",
  "messages": [
    {"role": "user", "content": "写一篇长文章"}
  ],
  "stream": true
}
```

**兼容性模式**
```bash
# 启用兼容性模式
export COMPATIBILITY_MODE=true
```
此模式下，所有 `system` 消息会转换为 `user` 消息，提高与某些客户端的兼容性。

---

## 💬 交流群

欢迎加入 QQ 群交流讨论！

**QQ 群号：1083250744**



---

## 许可证与免责声明

本项目仅供学习和研究用途。使用本项目表示您同意：
- 不将本项目用于任何商业用途
- 承担使用本项目的所有风险和责任
- 遵守相关的服务条款和法律法规

项目作者对因使用本项目而产生的任何直接或间接损失不承担责任。

## ⚠️ 许可证声明

**本项目采用 Cooperative Non-Commercial License (CNC-1.0)**

这是一个反商业化的严格开源协议，详情请查看 [LICENSE](LICENSE) 文件。

### ✅ 允许的用途：
- 个人学习、研究、教育用途
- 非营利组织使用
- 开源项目集成（需遵循相同协议）
- 学术研究和论文发表

### ❌ 禁止的用途：
- 任何形式的商业使用
- 年收入超过100万美元的企业使用
- 风投支持或公开交易的公司使用  
- 提供付费服务或产品
- 商业竞争用途

---

## File: docs/README_EN.md

# GeminiCLI to API

**Convert GeminiCLI and Antigravity to OpenAI, GEMINI, and Claude API Compatible Interfaces**

[](https://www.python.org/downloads/)
[](../LICENSE)
[](https://github.com/su-kaka/gcli2api/pkgs/container/gcli2api)

[中文](../README.md) | English | [日本語](./README_JA.md)

## 🚀 Quick Deploy

[](https://zeabur.com/templates/97VMEF?referralCode=sukaka)
[](https://render.com/deploy?repo=https://github.com/su-kaka/gcli2api)
---

## Installation Guide

### Termux Environment

**Initial Installation**
```bash
curl -o termux-install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/termux-install.sh" && chmod +x termux-install.sh && ./termux-install.sh
```

**Restart Service**
```bash
cd gcli2api
bash termux-start.sh
```

### Windows Environment

**Initial Installation**
```powershell
iex (iwr "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/install.ps1" -UseBasicParsing).Content
```

**Restart Service**
Double-click to execute `start.bat`

### Linux Environment

**Initial Installation**
```bash
curl -o install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/install.sh" && chmod +x install.sh && ./install.sh
```

**Restart Service**
```bash
cd gcli2api
bash start.sh
```

### macOS Environment

**Initial Installation**
```bash
curl -o darwin-install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/darwin-install.sh" && chmod +x darwin-install.sh && ./darwin-install.sh
```

**Restart Service**
```bash
cd gcli2api
bash start.sh
```

### Docker Environment

**Docker Run Command**
```bash
# Using universal password
docker run -d --name gcli2api --network host -e PASSWORD=pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds ghcr.io/su-kaka/gcli2api:latest

# Using separate passwords
docker run -d --name gcli2api --network host -e API_PASSWORD=api_pwd -e PANEL_PASSWORD=panel_pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds ghcr.io/su-kaka/gcli2api:latest
```

**Docker Mac**
```bash
# Using universal password
docker run -d \
  --name gcli2api \
  -p 7861:7861 \
  -p 8080:8080 \
  -e PASSWORD=pwd \
  -e PORT=7861 \
  -v "$(pwd)/data/creds":/app/creds \
  ghcr.io/su-kaka/gcli2api:latest
```

```bash
# Using separate passwords
docker run -d \
--name gcli2api \
-p 7861:7861 \
-p 8080:8080 \
-e API_PASSWORD=api_pwd \
-e PANEL_PASSWORD=panel_pwd \
-e PORT=7861 \
-v $(pwd)/data/creds:/app/creds \
ghcr.io/su-kaka/gcli2api:latest
```

**Docker Compose Run Command**
1. Save the following content as `docker-compose.yml` file:
    ```yaml
    version: '3.8'

    services:
      gcli2api:
        image: ghcr.io/su-kaka/gcli2api:latest
        container_name: gcli2api
        restart: unless-stopped
        network_mode: host
        environment:
          # Using universal password (recommended for simple deployment)
          - PASSWORD=pwd
          - PORT=7861
          # Or use separate passwords (recommended for production)
          # - API_PASSWORD=your_api_password
          # - PANEL_PASSWORD=your_panel_password
        volumes:
          - ./data/creds:/app/creds
        healthcheck:
          test: ["CMD-SHELL", "python -c \"import sys, urllib.request, os; port = os.environ.get('PORT', '7861'); req = urllib.request.Request(f'http://localhost:{port}/v1/models', headers={'Authorization': 'Bearer ' + os.environ.get('PASSWORD', 'pwd')}); sys.exit(0 if urllib.request.urlopen(req, timeout=5).getcode() == 200 else 1)\""]
          interval: 30s
          timeout: 10s
          retries: 3
          start_period: 40s
    ```
2. Start the service:
    ```bash
    docker-compose up -d
    ```

## Core Features

### 🔄 API Endpoints and Format Support

**Multi-endpoint Multi-format Support**
- **OpenAI Compatible Endpoints**: `/v1/chat/completions` and `/v1/models`
  - Supports standard OpenAI format (messages structure)
  - Supports Gemini native format (contents structure)
  - Automatic format detection and conversion, no manual switching required
  - Supports multimodal input (text + images)
- **Gemini Native Endpoints**: `/v1/models/{model}:generateContent` and `streamGenerateContent`
  - Supports complete Gemini native API specifications
  - Multiple authentication methods: Bearer Token, x-goog-api-key header, URL parameter key
- **Claude Format Compatibility**: Full support for Claude API format
  - Endpoint: `/v1/messages` (follows Claude API specification)
  - Supports Claude standard messages format
  - Supports system parameter and Claude-specific features
  - Automatically converts to backend-supported format
- **Antigravity API Support**: Supports OpenAI, Gemini, and Claude formats
  - OpenAI format endpoint: `/antigravity/v1/chat/completions`
  - Gemini format endpoint: `/antigravity/v1/models/{model}:generateContent` and `streamGenerateContent`
  - Claude format endpoint: `/antigravity/v1/messages`
  - Supports all Antigravity models (Claude, Gemini, etc.)
  - Automatic model name mapping and thinking mode detection

### 🔐 Authentication and Security Management

**Flexible Password Management**
- **Separate Password Support**: API password (chat endpoints) and control panel password can be set independently
- **Multiple Authentication Methods**: Supports Authorization Bearer, x-goog-api-key header, URL parameters, etc.
- **JWT Token Authentication**: Control panel supports JWT token authentication
- **User Email Retrieval**: Automatically retrieves and displays Google account email addresses

### 📊 Intelligent Credential Management System

**Advanced Credential Management**
- Multiple Google OAuth credential automatic rotation
- Enhanced stability through redundant authentication
- Load balancing and concurrent request support
- Automatic failure detection and credential disabling
- Credential usage statistics and quota management
- Support for manual enable/disable credential files
- Batch credential file operations (enable, disable, delete)

**Credential Status Monitoring**
- Real-time credential health checks
- Error code tracking (429, 403, 500, etc.)
- Automatic banning mechanism (configurable)

### 🌊 Streaming and Response Processing

**Multiple Streaming Support**
- True real-time streaming responses
- Fake streaming mode (for compatibility)
- Streaming anti-truncation feature (prevents answer truncation)
- Asynchronous task management and timeout handling

**Response Optimization**
- Thinking chain content separation
- Reasoning process (reasoning_content) handling
- Multi-turn conversation context management
- Compatibility mode (converts system messages to user messages)

### 🎛️ Web Management Console

**Full-featured Web Interface**
- OAuth authentication flow management (supports GCLI and Antigravity dual modes)
- Credential file upload, download, and management
- Real-time log viewing (WebSocket)
- System configuration management
- Usage statistics and monitoring dashboard
- Mobile-friendly interface

**Batch Operation Support**
- ZIP file batch credential upload (GCLI and Antigravity)
- Batch enable/disable/delete credentials
- Batch user email retrieval
- Batch configuration management
- Unified batch upload interface for all credential types

### 📈 Usage Monitoring

**Real-time Monitoring**
- WebSocket real-time log streams
- System status monitoring
- Credential health status

### 🔧 Advanced Configuration and Customization

**Network and Proxy Configuration**
- HTTP/HTTPS proxy support
- Proxy endpoint configuration (OAuth, Google APIs, metadata service)
- Timeout and retry configuration
- Network error handling and recovery

**Performance and Stability Configuration**
- 429 error automatic retry (configurable interval and attempts)
- Anti-truncation maximum retry attempts

**Logging and Debugging**
- Multi-level logging system (DEBUG, INFO, WARNING, ERROR)
- Log file management
- Real-time log streams
- Log download and clearing

### 🔄 Environment Variables and Configuration Management

**Flexible Configuration Methods**
- Environment variable configuration
- Hot configuration updates (partial configuration items)
- Configuration locking (environment variable priority)

## Supported Models

All models have 1M context window capacity. Each credential file provides 1000 request quota.

### 🤖 Base Models
- `gemini-2.5-pro`
- `gemini-3-pro-preview`
- `gemini-3.1-pro-preview`

### 🧠 Thinking Models
- `gemini-2.5-pro-high`: Thinking mode
- `gemini-2.5-pro-low`: Low thinking mode
- Supports custom thinking budget configuration
- Automatic separation of thinking content and final answers

### 🔍 Search-Enhanced Models
- `gemini-2.5-pro-search`: Model with integrated search functionality

### 🖼️ Image Generation Models (Antigravity)
- `gemini-3.1-flash-image`: Base image generation model
- **Resolution Suffixes**:
  - `-2k`: 2K resolution
  - `-4k`: 4K HD resolution
- **Aspect Ratio Suffixes**:
  - `-1x1`: Square (avatar)
  - `-16x9`: Landscape (desktop wallpaper)
  - `-9x16`: Portrait (mobile wallpaper)
  - `-21x9`: Ultra-wide (ultrawide monitor)
  - `-4x3`: Traditional display
  - `-3x4`: Portrait poster
- **Combination Examples**:
  - `gemini-3.1-flash-image-4k-16x9`: 4K landscape
  - `gemini-3.1-flash-image-2k-9x16`: 2K portrait
- When no ratio is specified, the API automatically decides the aspect ratio

### 🌊 Special Feature Variants
- **Fake Streaming Mode**: Add `-假流式` suffix to any model name
  - Example: `gemini-2.5-pro-假流式`
  - For scenarios requiring streaming responses but server doesn't support true streaming
- **Streaming Anti-truncation Mode**: Add `流式抗截断/` prefix to model name
  - Example: `流式抗截断/gemini-2.5-pro`
  - Automatically detects response truncation and retries to ensure complete answers

### 🔧 Automatic Model Feature Detection
- System automatically recognizes feature identifiers in model names
- Transparently handles feature mode transitions
- Supports feature combination usage

---

## Configuration Instructions

1. Visit `http://127.0.0.1:7861` (default port, modifiable via PORT environment variable)
2. Complete OAuth authentication flow (default password: `pwd`, modifiable via environment variables)
   - **GCLI Mode**: For obtaining Google Cloud Gemini API credentials
   - **Antigravity Mode**: For obtaining Google Antigravity API credentials
3. Configure client:

**OpenAI Compatible Client:**
   - **Endpoint Address**: `http://127.0.0.1:7861/v1`
   - **API Key**: `pwd` (default value, modifiable via API_PASSWORD or PASSWORD environment variables)

**Gemini Native Client:**
   - **Endpoint Address**: `http://127.0.0.1:7861`
   - **Authentication Methods**:
     - `Authorization: Bearer your_api_password`
     - `x-goog-api-key: your_api_password`
     - URL parameter: `?key=your_api_password`

### 🌟 Dual Authentication Mode Support

**GCLI Authentication Mode**
- Standard Google Cloud Gemini API authentication
- Supports OAuth2.0 authentication flow
- Automatically enables required Google Cloud APIs

**Antigravity Authentication Mode**
- Dedicated authentication for Google Antigravity API
- Independent credential management system
- Supports batch upload and management
- Completely isolated from GCLI credentials

**Unified Management Interface**
- Manage both credential types in the "Batch Upload" tab
- Upper section: GCLI credential batch upload (blue theme)
- Lower section: Antigravity credential batch upload (green theme)
- Separate credential management tabs for each type

## 💾 Data Storage Mode

### 🌟 Storage Backend Support

gcli2api supports two storage backends: **Local SQLite (Default)** and **MongoDB (Cloud Distributed Storage)**

### 📁 Local SQLite Storage (Default)

**Default Storage Method**
- No configuration required, works out of the box
- Data is stored in a local SQLite database
- Suitable for single-machine deployment and personal use
- Automatically creates and manages database files

### 🍃 MongoDB Cloud Storage Mode

**Cloud Distributed Storage Solution**

When multi-instance deployment or cloud storage is needed, MongoDB storage mode can be enabled.

### ⚙️ Enable MongoDB Mode

**Step 1: Configure MongoDB Connection**
```bash
# Local MongoDB
export MONGODB_URI="mongodb://localhost:27017"

# MongoDB Atlas cloud service
export MONGODB_URI="mongodb+srv://username:password@cluster.mongodb.net"

# MongoDB with authentication
export MONGODB_URI="mongodb://admin:password@localhost:27017/admin"

# Optional: Custom database name (default: gcli2api)
export MONGODB_DATABASE="my_gcli_db"
```

**Step 2: Start Application**
```bash
# Application will automatically detect MongoDB configuration and use MongoDB storage
python web.py
```

**Docker Environment using MongoDB**
```bash
# Single MongoDB deployment
docker run -d --name gcli2api \
  -e MONGODB_URI="mongodb://mongodb:27017" \
  -e API_PASSWORD=your_password \
  --network your_network \
  ghcr.io/su-kaka/gcli2api:latest

# Using MongoDB Atlas
docker run -d --name gcli2api \
  -e MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/gcli2api" \
  -e API_PASSWORD=your_password \
  -p 7861:7861 \
  ghcr.io/su-kaka/gcli2api:latest
```

**Docker Compose Example**
```yaml
version: '3.8'

services:
  mongodb:
    image: mongo:7
    container_name: gcli2api-mongodb
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password123
    volumes:
      - mongodb_data:/data/db
    ports:
      - "27017:27017"

  gcli2api:
    image: ghcr.io/su-kaka/gcli2api:latest
    container_name: gcli2api
    restart: unless-stopped
    depends_on:
      - mongodb
    environment:
      - MONGODB_URI=mongodb://admin:password123@mongodb:27017/admin
      - MONGODB_DATABASE=gcli2api
      - API_PASSWORD=your_api_password
      - PORT=7861
    ports:
      - "7861:7861"

volumes:
  mongodb_data:
```


### 🔧 Advanced Configuration

**MongoDB Connection Optimization**
```bash
# Connection pool and timeout configuration
export MONGODB_URI="mongodb://localhost:27017?maxPoolSize=10&serverSelectionTimeoutMS=5000"

# Replica set configuration
export MONGODB_URI="mongodb://host1:27017,host2:27017,host3:27017/gcli2api?replicaSet=myReplicaSet"

# Read-write separation configuration
export MONGODB_URI="mongodb://localhost:27017/gcli2api?readPreference=secondaryPreferred"
```

### Environment Variable Configuration

**Basic Configuration**
- `PORT`: Service port (default: 7861)
- `HOST`: Server listen address (default: 0.0.0.0)

**Password Configuration**
- `API_PASSWORD`: Chat API access password (default: inherits PASSWORD or pwd)
- `PANEL_PASSWORD`: Control panel access password (default: inherits PASSWORD or pwd)
- `PASSWORD`: Universal password, overrides the above two when set (default: pwd)

**Performance and Stability Configuration**
- `RETRY_429_ENABLED`: Enable 429 error automatic retry (default: true)
- `RETRY_429_MAX_RETRIES`: Maximum retry attempts for 429 errors (default: 3)
- `RETRY_429_INTERVAL`: Retry interval for 429 errors, in seconds (default: 1.0)
- `ANTI_TRUNCATION_MAX_ATTEMPTS`: Maximum retry attempts for anti-truncation (default: 3)

**Network and Proxy Configuration**
- `PROXY`: HTTP/HTTPS proxy address (format: `http://host:port`)
- `OAUTH_PROXY_URL`: OAuth authentication proxy endpoint
- `GOOGLEAPIS_PROXY_URL`: Google APIs proxy endpoint
- `METADATA_SERVICE_URL`: Metadata service proxy endpoint

**Automation Configuration**
- `AUTO_BAN`: Enable automatic credential banning (default: true)
- `AUTO_LOAD_ENV_CREDS`: Automatically load environment variable credentials at startup (default: false)

**Compatibility Configuration**
- `COMPATIBILITY_MODE`: Enable compatibility mode, converts system messages to user messages (default: false)

**Logging Configuration**
- `LOG_LEVEL`: Log level (DEBUG/INFO/WARNING/ERROR, default: INFO)
- `LOG_FILE`: Log file path (default: log.txt)

**Storage Configuration**

**SQLite Configuration (Default)**
- No configuration required, automatically uses local SQLite database
- Database files are automatically created in the project directory

**MongoDB Configuration (Optional Cloud Storage)**
- `MONGODB_URI`: MongoDB connection string (enables MongoDB mode when set)
- `MONGODB_DATABASE`: MongoDB database name (default: gcli2api)

**Docker Usage Example**
```bash
# Using universal password
docker run -d --name gcli2api \
  -e PASSWORD=mypassword \
  -e PORT=7861 \
  ghcr.io/su-kaka/gcli2api:latest

# Using separate passwords
docker run -d --name gcli2api \
  -e API_PASSWORD=my_api_password \
  -e PANEL_PASSWORD=my_panel_password \
  -e PORT=7861 \
  ghcr.io/su-kaka/gcli2api:latest
```

Note: When credential environment variables are set, the system will prioritize using credentials from environment variables and ignore files in the `creds` directory.

### API Usage Methods

This service supports multiple complete sets of API endpoints:

#### 1. OpenAI Compatible Endpoints (GCLI)

**Endpoint:** `/v1/chat/completions`
**Authentication:** `Authorization: Bearer your_api_password`

Supports two request formats with automatic detection and processing:

**OpenAI Format:**
```json
{
  "model": "gemini-2.5-pro",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "stream": true
}
```

**Gemini Native Format:**
```json
{
  "model": "gemini-2.5-pro",
  "contents": [
    {"role": "user", "parts": [{"text": "Hello"}]}
  ],
  "systemInstruction": {"parts": [{"text": "You are a helpful assistant"}]},
  "generationConfig": {
    "temperature": 0.7
  }
}
```

#### 2. Gemini Native Endpoints (GCLI)

**Non-streaming Endpoint:** `/v1/models/{model}:generateContent`
**Streaming Endpoint:** `/v1/models/{model}:streamGenerateContent`
**Model List:** `/v1/models`

**Authentication Methods (choose one):**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URL parameter: `?key=your_api_password`

**Request Examples:**
```bash
# Using x-goog-api-key header
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'

# Using URL parameter
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-pro:streamGenerateContent?key=your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'
```

#### 3. Claude API Format Endpoints

**Endpoint:** `/v1/messages`
**Authentication:** `x-api-key: your_api_password` or `Authorization: Bearer your_api_password`

**Request Example:**
```bash
curl -X POST "http://127.0.0.1:7861/v1/messages" \
  -H "x-api-key: your_api_password" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'
```

**Support for system parameter:**
```json
{
  "model": "gemini-2.5-pro",
  "max_tokens": 1024,
  "system": "You are a helpful assistant",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}
```

**Notes:**
- Fully compatible with Claude API format specification
- Automatically converts to Gemini format for backend calls
- Supports all Claude standard parameters
- Response format follows Claude API specification

#### 4. Antigravity API Endpoints

**Supports three formats: OpenAI, Gemini, and Claude**

##### Antigravity OpenAI Format Endpoints

**Endpoint:** `/antigravity/v1/chat/completions`
**Authentication:** `Authorization: Bearer your_api_password`

**Request Example:**
```bash
curl -X POST "http://127.0.0.1:7861/antigravity/v1/chat/completions" \
  -H "Authorization: Bearer your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": true
  }'
```

##### Antigravity Gemini Format Endpoints

**Non-streaming Endpoint:** `/antigravity/v1/models/{model}:generateContent`
**Streaming Endpoint:** `/antigravity/v1/models/{model}:streamGenerateContent`

**Authentication Methods (choose one):**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URL parameter: `?key=your_api_password`

**Request Examples:**
```bash
# Gemini format non-streaming request
curl -X POST "http://127.0.0.1:7861/antigravity/v1/models/claude-sonnet-4-5:generateContent" \
  -H "x-goog-api-key: your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ],
    "generationConfig": {
      "temperature": 0.7
    }
  }'

# Gemini format streaming request
curl -X POST "http://127.0.0.1:7861/antigravity/v1/models/gemini-2.5-flash:streamGenerateContent?key=your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'
```

##### Antigravity Claude Format Endpoints

**Endpoint:** `/antigravity/v1/messages`
**Authentication:** `x-api-key: your_api_password`

**Request Example:**
```bash
curl -X POST "http://127.0.0.1:7861/antigravity/v1/messages" \
  -H "x-api-key: your_api_password" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'
```

**Supported Antigravity Models:**
- Claude series: `claude-sonnet-4-5`, `claude-opus-4-5`, etc.
- Gemini series: `gemini-2.5-flash`, `gemini-2.5-pro`, etc.
- Automatically supports thinking models

**Gemini Native Example:**
```python
from io import BytesIO
from PIL import Image
from google.genai import Client
from google.genai.types import HttpOptions
from google.genai import types
# The client gets the API key from the environment variable `GEMINI_API_KEY`.

client = Client(
            api_key="pwd",
            http_options=HttpOptions(base_url="http://127.0.0.1:7861"),
        )

prompt = (
    """
    Draw a cat
    """
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents=[prompt],
    config=types.GenerateContentConfig(
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
        )
    )
)
for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        image = Image.open(BytesIO(part.inline_data.data))
        image.save("generated_image.png")

```

**Notes:**
- OpenAI endpoints return OpenAI-compatible format
- Gemini endpoints return Gemini native format
- Both endpoints use the same API password

## 📋 Complete API Reference

### Web Console API

**Authentication Endpoints**
- `POST /auth/login` - User login
- `POST /auth/start` - Start OAuth authentication (supports GCLI and Antigravity modes)
- `POST /auth/callback` - Handle OAuth callback
- `POST /auth/callback-url` - Complete authentication directly from callback URL
- `GET /auth/status/{project_id}` - Check authentication status

**Credential Management Endpoints** (supports `mode=geminicli` or `mode=antigravity` parameter)
- `POST /creds/upload` - Batch upload credential files (supports JSON and ZIP)
- `GET /creds/status` - Get credential status list (supports pagination and filtering)
- `GET /creds/detail/{filename}` - Get single credential details
- `POST /creds/action` - Single credential operation (enable/disable/delete)
- `POST /creds/batch-action` - Batch credential operations
- `GET /creds/download/{filename}` - Download single credential file
- `GET /creds/download-all` - Package download all credentials
- `POST /creds/fetch-email/{filename}` - Get user email
- `POST /creds/refresh-all-emails` - Batch refresh user emails
- `POST /creds/deduplicate-by-email` - Deduplicate credentials by email
- `POST /creds/verify-project/{filename}` - Verify credential Project ID
- `GET /creds/quota/{filename}` - Get credential quota information (Antigravity only)

**Configuration Management Endpoints**
- `GET /config/get` - Get current configuration
- `POST /config/save` - Save configuration

**Log Management Endpoints**
- `POST /logs/clear` - Clear logs
- `GET /logs/download` - Download log file
- `WebSocket /logs/stream` - Real-time log stream

**Version Information Endpoints**
- `GET /version/info` - Get version information (optional `check_update=true` parameter to check for updates)

### Chat API Features

**Multimodal Support**
```json
{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA..."
          }
        }
      ]
    }
  ]
}
```

**Thinking Mode Support**
```json
{
  "model": "gemini-2.5-pro-high",
  "messages": [
    {"role": "user", "content": "Complex math problem"}
  ]
}
```

Response will include separated thinking content:
```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Final answer",
      "reasoning_content": "Detailed thought process..."
    }
  }]
}
```

**Streaming Anti-truncation Usage**
```json
{
  "model": "流式抗截断/gemini-2.5-pro",
  "messages": [
    {"role": "user", "content": "Write a long article"}
  ],
  "stream": true
}
```

**Compatibility Mode**
```bash
# Enable compatibility mode
export COMPATIBILITY_MODE=true
```
In this mode, all `system` messages are converted to `user` messages, improving compatibility with certain clients.

---

## 💬 Community

Welcome to join the QQ group for discussion!

**QQ Group: 1083250744**



---

## License and Disclaimer

This project is for learning and research purposes only. Using this project indicates that you agree to:
- Not use this project for any commercial purposes
- Bear all risks and responsibilities of using this project
- Comply with relevant terms of service and legal regulations

The project authors are not responsible for any direct or indirect losses arising from the use of this project.

## ⚠️ License Declaration

**This project is licensed under the Cooperative Non-Commercial License (CNC-1.0)**

This is a strict anti-commercial open source license. Please refer to the [LICENSE](../LICENSE) file for details.

### ✅ Permitted Uses:
- Personal learning, research, and educational purposes
- Non-profit organization use
- Open source project integration (must comply with the same license)
- Academic research and publication

### ❌ Prohibited Uses:
- Any form of commercial use
- Enterprise use with annual revenue exceeding $1 million
- Venture capital-backed or publicly traded companies
- Providing paid services or products
- Commercial competitive use

---

## File: docs/README_JA.md

# GeminiCLI to API

**GeminiCLIおよびAntigravityをOpenAI、GEMINI、Claude API互換インターフェースに変換**

[](https://www.python.org/downloads/)
[](../LICENSE)
[](https://github.com/su-kaka/gcli2api/pkgs/container/gcli2api)

[中文](../README.md) | [English](README_EN.md) | 日本語

## 🚀 クイックデプロイ

[](https://zeabur.com/templates/97VMEF?referralCode=sukaka)
[](https://render.com/deploy?repo=https://github.com/su-kaka/gcli2api)
---

## インストールガイド

### Termux環境

**初期インストール**
```bash
curl -o termux-install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/termux-install.sh" && chmod +x termux-install.sh && ./termux-install.sh
```

**サービス再起動**
```bash
cd gcli2api
bash termux-start.sh
```

### Windows環境

**初期インストール**
```powershell
iex (iwr "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/install.ps1" -UseBasicParsing).Content
```

**サービス再起動**
`start.bat` をダブルクリックして実行

### Linux環境

**初期インストール**
```bash
curl -o install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/install.sh" && chmod +x install.sh && ./install.sh
```

**サービス再起動**
```bash
cd gcli2api
bash start.sh
```

### macOS環境

**初期インストール**
```bash
curl -o darwin-install.sh "https://raw.githubusercontent.com/su-kaka/gcli2api/refs/heads/master/darwin-install.sh" && chmod +x darwin-install.sh && ./darwin-install.sh
```

**サービス再起動**
```bash
cd gcli2api
bash start.sh
```

### Docker環境

**Docker Runコマンド**
```bash
# 共通パスワードを使用
docker run -d --name gcli2api --network host -e PASSWORD=pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds ghcr.io/su-kaka/gcli2api:latest

# 個別パスワードを使用
docker run -d --name gcli2api --network host -e API_PASSWORD=api_pwd -e PANEL_PASSWORD=panel_pwd -e PORT=7861 -v $(pwd)/data/creds:/app/creds ghcr.io/su-kaka/gcli2api:latest
```

**Docker Mac**
```bash
# 共通パスワードを使用
docker run -d \
  --name gcli2api \
  -p 7861:7861 \
  -p 8080:8080 \
  -e PASSWORD=pwd \
  -e PORT=7861 \
  -v "$(pwd)/data/creds":/app/creds \
  ghcr.io/su-kaka/gcli2api:latest
```

```bash
# 個別パスワードを使用
docker run -d \
--name gcli2api \
-p 7861:7861 \
-p 8080:8080 \
-e API_PASSWORD=api_pwd \
-e PANEL_PASSWORD=panel_pwd \
-e PORT=7861 \
-v $(pwd)/data/creds:/app/creds \
ghcr.io/su-kaka/gcli2api:latest
```

**Docker Compose Runコマンド**
1. 以下の内容を `docker-compose.yml` ファイルとして保存:
    ```yaml
    version: '3.8'

    services:
      gcli2api:
        image: ghcr.io/su-kaka/gcli2api:latest
        container_name: gcli2api
        restart: unless-stopped
        network_mode: host
        environment:
          # 共通パスワードを使用（シンプルなデプロイに推奨）
          - PASSWORD=pwd
          - PORT=7861
          # または個別パスワードを使用（本番環境に推奨）
          # - API_PASSWORD=your_api_password
          # - PANEL_PASSWORD=your_panel_password
        volumes:
          - ./data/creds:/app/creds
        healthcheck:
          test: ["CMD-SHELL", "python -c \"import sys, urllib.request, os; port = os.environ.get('PORT', '7861'); req = urllib.request.Request(f'http://localhost:{port}/v1/models', headers={'Authorization': 'Bearer ' + os.environ.get('PASSWORD', 'pwd')}); sys.exit(0 if urllib.request.urlopen(req, timeout=5).getcode() == 200 else 1)\""]
          interval: 30s
          timeout: 10s
          retries: 3
          start_period: 40s
    ```
2. サービスを起動:
    ```bash
    docker-compose up -d
    ```

## コア機能

### 🔄 APIエンドポイントとフォーマット対応

**マルチエンドポイント・マルチフォーマット対応**
- **OpenAI互換エンドポイント**: `/v1/chat/completions` および `/v1/models`
  - 標準OpenAIフォーマット（messages構造）に対応
  - Geminiネイティブフォーマット（contents構造）に対応
  - フォーマットの自動検出・変換、手動切替不要
  - マルチモーダル入力に対応（テキスト＋画像）
- **Geminiネイティブエンドポイント**: `/v1/models/{model}:generateContent` および `streamGenerateContent`
  - Geminiネイティブ API仕様に完全対応
  - 複数の認証方式: Bearer Token、x-goog-api-keyヘッダー、URLパラメータkey
- **Claudeフォーマット互換**: Claude APIフォーマットに完全対応
  - エンドポイント: `/v1/messages`（Claude API仕様に準拠）
  - Claude標準messagesフォーマットに対応
  - systemパラメータおよびClaude固有機能に対応
  - バックエンド対応フォーマットへの自動変換
- **Antigravity API対応**: OpenAI、Gemini、Claudeフォーマットに対応
  - OpenAIフォーマットエンドポイント: `/antigravity/v1/chat/completions`
  - Geminiフォーマットエンドポイント: `/antigravity/v1/models/{model}:generateContent` および `streamGenerateContent`
  - Claudeフォーマットエンドポイント: `/antigravity/v1/messages`
  - 全Antigravityモデルに対応（Claude、Geminiなど）
  - モデル名の自動マッピングおよびThinkingモード検出

### 🔐 認証とセキュリティ管理

**柔軟なパスワード管理**
- **個別パスワード対応**: APIパスワード（チャットエンドポイント）とコントロールパネルパスワードを個別に設定可能
- **複数の認証方式**: Authorization Bearer、x-goog-api-keyヘッダー、URLパラメータなどに対応
- **JWTトークン認証**: コントロールパネルはJWTトークン認証に対応
- **ユーザーメール取得**: Googleアカウントのメールアドレスを自動取得・表示

### 📊 インテリジェントなクレデンシャル管理システム

**高度なクレデンシャル管理**
- 複数のGoogle OAuthクレデンシャルの自動ローテーション
- 冗長認証による安定性の向上
- ロードバランシングと同時リクエスト対応
- 自動障害検出とクレデンシャル無効化
- クレデンシャル使用統計とクォータ管理
- クレデンシャルファイルの手動有効化/無効化に対応
- クレデンシャルファイルの一括操作（有効化、無効化、削除）

**クレデンシャルステータス監視**
- リアルタイムのクレデンシャルヘルスチェック
- エラーコードの追跡（429、403、500など）
- 自動BAN機能（設定可能）

### 🌊 ストリーミングとレスポンス処理

**複数のストリーミング対応**
- リアルタイムストリーミングレスポンス
- 疑似ストリーミングモード（互換性向上用）
- ストリーミング途切れ防止機能（回答の途切れを防止）
- 非同期タスク管理とタイムアウト処理

**レスポンス最適化**
- 思考チェーン内容の分離
- 推論プロセス（reasoning_content）の処理
- マルチターン会話のコンテキスト管理
- 互換モード（systemメッセージをuserメッセージに変換）

### 🎛️ Web管理コンソール

**フル機能のWebインターフェース**
- OAuth認証フロー管理（GCLIおよびAntigravityデュアルモード対応）
- クレデンシャルファイルのアップロード、ダウンロード、管理
- リアルタイムログ表示（WebSocket）
- システム設定管理
- 使用統計と監視ダッシュボード
- モバイル対応インターフェース

**一括操作対応**
- ZIPファイルによるクレデンシャル一括アップロード（GCLIおよびAntigravity）
- クレデンシャルの一括有効化/無効化/削除
- ユーザーメールの一括取得
- 設定の一括管理
- 全クレデンシャルタイプ統合一括アップロードインターフェース

### 📈 使用状況モニタリング

**リアルタイム監視**
- WebSocketリアルタイムログストリーム
- システムステータス監視
- クレデンシャルヘルスステータス

### 🔧 高度な設定とカスタマイズ

**ネットワークとプロキシ設定**
- HTTP/HTTPSプロキシ対応
- プロキシエンドポイント設定（OAuth、Google APIs、メタデータサービス）
- タイムアウトとリトライ設定
- ネットワークエラー処理とリカバリ

**パフォーマンスと安定性の設定**
- 429エラーの自動リトライ（間隔と回数を設定可能）
- 途切れ防止の最大リトライ回数

**ログとデバッグ**
- マルチレベルログシステム（DEBUG、INFO、WARNING、ERROR）
- ログファイル管理
- リアルタイムログストリーム
- ログのダウンロードとクリア

### 🔄 環境変数と設定管理

**柔軟な設定方法**
- 環境変数による設定
- ホット設定更新（一部設定項目）
- 設定ロック（環境変数優先）

## 対応モデル

全モデルが100万トークンのコンテキストウィンドウに対応。各クレデンシャルファイルで1000リクエストのクォータを提供。

### 🤖 基本モデル
- `gemini-2.5-pro`
- `gemini-3-pro-preview`
- `gemini-3.1-pro-preview`

### 🧠 Thinkingモデル
- `gemini-2.5-pro-high`: Thinkingモード
- `gemini-2.5-pro-low`: 低Thinkingモード
- カスタムThinkingバジェット設定に対応
- 思考内容と最終回答の自動分離

### 🔍 検索拡張モデル
- `gemini-2.5-pro-search`: 検索機能統合モデル

### 🖼️ 画像生成モデル（Antigravity）
- `gemini-3.1-flash-image`: 基本画像生成モデル
- **解像度サフィックス**:
  - `-2k`: 2K解像度
  - `-4k`: 4K HD解像度
- **アスペクト比サフィックス**:
  - `-1x1`: 正方形（アバター）
  - `-16x9`: 横長（デスクトップ壁紙）
  - `-9x16`: 縦長（モバイル壁紙）
  - `-21x9`: ウルトラワイド（ウルトラワイドモニター）
  - `-4x3`: 従来のディスプレイ
  - `-3x4`: 縦型ポスター
- **組み合わせ例**:
  - `gemini-3.1-flash-image-4k-16x9`: 4K横長
  - `gemini-3.1-flash-image-2k-9x16`: 2K縦長
- 比率未指定時はAPIが自動的にアスペクト比を決定

### 🌊 特殊機能バリアント
- **疑似ストリーミングモード**: 任意のモデル名に `-假流式` サフィックスを追加
  - 例: `gemini-2.5-pro-假流式`
  - ストリーミングレスポンスが必要だがサーバーが真のストリーミングに対応していない場合に使用
- **ストリーミング途切れ防止モード**: モデル名に `流式抗截断/` プレフィックスを追加
  - 例: `流式抗截断/gemini-2.5-pro`
  - レスポンスの途切れを自動検出しリトライして完全な回答を保証

### 🔧 モデル機能の自動検出
- システムがモデル名内の機能識別子を自動認識
- 機能モード切替を透過的に処理
- 機能の組み合わせ使用に対応

---

## 設定手順

1. `http://127.0.0.1:7861` にアクセス（デフォルトポート、PORT環境変数で変更可能）
2. OAuth認証フローを完了（デフォルトパスワード: `pwd`、環境変数で変更可能）
   - **GCLIモード**: Google Cloud Gemini APIクレデンシャルの取得用
   - **Antigravityモード**: Google Antigravity APIクレデンシャルの取得用
3. クライアントを設定:

**OpenAI互換クライアント:**
   - **エンドポイントアドレス**: `http://127.0.0.1:7861/v1`
   - **APIキー**: `pwd`（デフォルト値、API_PASSWORDまたはPASSWORD環境変数で変更可能）

**Geminiネイティブクライアント:**
   - **エンドポイントアドレス**: `http://127.0.0.1:7861`
   - **認証方式**:
     - `Authorization: Bearer your_api_password`
     - `x-goog-api-key: your_api_password`
     - URLパラメータ: `?key=your_api_password`

### 🌟 デュアル認証モード対応

**GCLI認証モード**
- 標準Google Cloud Gemini API認証
- OAuth2.0認証フローに対応
- 必要なGoogle Cloud APIを自動的に有効化

**Antigravity認証モード**
- Google Antigravity API専用認証
- 独立したクレデンシャル管理システム
- 一括アップロードと管理に対応
- GCLIクレデンシャルとは完全に分離

**統合管理インターフェース**
- 「一括アップロード」タブで両方のクレデンシャルタイプを管理
- 上部セクション: GCLIクレデンシャル一括アップロード（青テーマ）
- 下部セクション: Antigravityクレデンシャル一括アップロード（緑テーマ）
- 各タイプ別のクレデンシャル管理タブ

## 💾 データストレージモード

### 🌟 ストレージバックエンド対応

gcli2apiは2つのストレージバックエンドに対応: **ローカルSQLite（デフォルト）** と **MongoDB（クラウド分散ストレージ）**

### 📁 ローカルSQLiteストレージ（デフォルト）

**デフォルトストレージ方式**
- 設定不要、すぐに利用可能
- データはローカルSQLiteデータベースに保存
- 単一マシンデプロイおよび個人利用に最適
- データベースファイルの自動作成・管理

### 🍃 MongoDBクラウドストレージモード

**クラウド分散ストレージソリューション**

マルチインスタンスデプロイやクラウドストレージが必要な場合、MongoDBストレージモードを有効にできます。

### ⚙️ MongoDBモードの有効化

**ステップ1: MongoDB接続の設定**
```bash
# ローカルMongoDB
export MONGODB_URI="mongodb://localhost:27017"

# MongoDB Atlasクラウドサービス
export MONGODB_URI="mongodb+srv://username:password@cluster.mongodb.net"

# 認証付きMongoDB
export MONGODB_URI="mongodb://admin:password@localhost:27017/admin"

# オプション: カスタムデータベース名（デフォルト: gcli2api）
export MONGODB_DATABASE="my_gcli_db"
```

**ステップ2: アプリケーションの起動**
```bash
# アプリケーションがMongoDB設定を自動検出し、MongoDBストレージを使用します
python web.py
```

**Docker環境でのMongoDB使用**
```bash
# 単一MongoDBデプロイ
docker run -d --name gcli2api \
  -e MONGODB_URI="mongodb://mongodb:27017" \
  -e API_PASSWORD=your_password \
  --network your_network \
  ghcr.io/su-kaka/gcli2api:latest

# MongoDB Atlasの使用
docker run -d --name gcli2api \
  -e MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/gcli2api" \
  -e API_PASSWORD=your_password \
  -p 7861:7861 \
  ghcr.io/su-kaka/gcli2api:latest
```

**Docker Composeの例**
```yaml
version: '3.8'

services:
  mongodb:
    image: mongo:7
    container_name: gcli2api-mongodb
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password123
    volumes:
      - mongodb_data:/data/db
    ports:
      - "27017:27017"

  gcli2api:
    image: ghcr.io/su-kaka/gcli2api:latest
    container_name: gcli2api
    restart: unless-stopped
    depends_on:
      - mongodb
    environment:
      - MONGODB_URI=mongodb://admin:password123@mongodb:27017/admin
      - MONGODB_DATABASE=gcli2api
      - API_PASSWORD=your_api_password
      - PORT=7861
    ports:
      - "7861:7861"

volumes:
  mongodb_data:
```


### 🔧 高度な設定

**MongoDB接続の最適化**
```bash
# コネクションプールとタイムアウト設定
export MONGODB_URI="mongodb://localhost:27017?maxPoolSize=10&serverSelectionTimeoutMS=5000"

# レプリカセット設定
export MONGODB_URI="mongodb://host1:27017,host2:27017,host3:27017/gcli2api?replicaSet=myReplicaSet"

# リード・ライト分離設定
export MONGODB_URI="mongodb://localhost:27017/gcli2api?readPreference=secondaryPreferred"
```

### 環境変数設定

**基本設定**
- `PORT`: サービスポート（デフォルト: 7861）
- `HOST`: サーバーリッスンアドレス（デフォルト: 0.0.0.0）

**パスワード設定**
- `API_PASSWORD`: チャットAPIアクセスパスワード（デフォルト: PASSWORDまたはpwdを継承）
- `PANEL_PASSWORD`: コントロールパネルアクセスパスワード（デフォルト: PASSWORDまたはpwdを継承）
- `PASSWORD`: 共通パスワード、設定時に上記2つを上書き（デフォルト: pwd）

**パフォーマンスと安定性の設定**
- `RETRY_429_ENABLED`: 429エラー自動リトライの有効化（デフォルト: true）
- `RETRY_429_MAX_RETRIES`: 429エラーの最大リトライ回数（デフォルト: 3）
- `RETRY_429_INTERVAL`: 429エラーのリトライ間隔、秒単位（デフォルト: 1.0）
- `ANTI_TRUNCATION_MAX_ATTEMPTS`: 途切れ防止の最大リトライ回数（デフォルト: 3）

**ネットワークとプロキシ設定**
- `PROXY`: HTTP/HTTPSプロキシアドレス（形式: `http://host:port`）
- `OAUTH_PROXY_URL`: OAuth認証プロキシエンドポイント
- `GOOGLEAPIS_PROXY_URL`: Google APIsプロキシエンドポイント
- `METADATA_SERVICE_URL`: メタデータサービスプロキシエンドポイント

**自動化設定**
- `AUTO_BAN`: クレデンシャル自動BANの有効化（デフォルト: true）
- `AUTO_LOAD_ENV_CREDS`: 起動時に環境変数クレデンシャルを自動ロード（デフォルト: false）

**互換性設定**
- `COMPATIBILITY_MODE`: 互換モードの有効化、systemメッセージをuserメッセージに変換（デフォルト: false）

**ログ設定**
- `LOG_LEVEL`: ログレベル（DEBUG/INFO/WARNING/ERROR、デフォルト: INFO）
- `LOG_FILE`: ログファイルパス（デフォルト: log.txt）

**ストレージ設定**

**SQLite設定（デフォルト）**
- 設定不要、自動的にローカルSQLiteデータベースを使用
- データベースファイルはプロジェクトディレクトリに自動作成

**MongoDB設定（オプションのクラウドストレージ）**
- `MONGODB_URI`: MongoDB接続文字列（設定時にMongoDBモードを有効化）
- `MONGODB_DATABASE`: MongoDBデータベース名（デフォルト: gcli2api）

**Docker使用例**
```bash
# 共通パスワードを使用
docker run -d --name gcli2api \
  -e PASSWORD=mypassword \
  -e PORT=7861 \
  ghcr.io/su-kaka/gcli2api:latest

# 個別パスワードを使用
docker run -d --name gcli2api \
  -e API_PASSWORD=my_api_password \
  -e PANEL_PASSWORD=my_panel_password \
  -e PORT=7861 \
  ghcr.io/su-kaka/gcli2api:latest
```

注意: クレデンシャル環境変数が設定されている場合、システムは環境変数のクレデンシャルを優先的に使用し、`creds` ディレクトリ内のファイルを無視します。

### API使用方法

本サービスは複数の完全なAPIエンドポイントセットに対応しています:

#### 1. OpenAI互換エンドポイント（GCLI）

**エンドポイント:** `/v1/chat/completions`
**認証:** `Authorization: Bearer your_api_password`

2つのリクエストフォーマットに対応し、自動検出・処理を行います:

**OpenAIフォーマット:**
```json
{
  "model": "gemini-2.5-pro",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Hello"}
  ],
  "temperature": 0.7,
  "stream": true
}
```

**Geminiネイティブフォーマット:**
```json
{
  "model": "gemini-2.5-pro",
  "contents": [
    {"role": "user", "parts": [{"text": "Hello"}]}
  ],
  "systemInstruction": {"parts": [{"text": "You are a helpful assistant"}]},
  "generationConfig": {
    "temperature": 0.7
  }
}
```

#### 2. Geminiネイティブエンドポイント（GCLI）

**非ストリーミングエンドポイント:** `/v1/models/{model}:generateContent`
**ストリーミングエンドポイント:** `/v1/models/{model}:streamGenerateContent`
**モデル一覧:** `/v1/models`

**認証方式（いずれか1つを選択）:**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URLパラメータ: `?key=your_api_password`

**リクエスト例:**
```bash
# x-goog-api-keyヘッダーを使用
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-pro:generateContent" \
  -H "x-goog-api-key: your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'

# URLパラメータを使用
curl -X POST "http://127.0.0.1:7861/v1/models/gemini-2.5-pro:streamGenerateContent?key=your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'
```

#### 3. Claude APIフォーマットエンドポイント

**エンドポイント:** `/v1/messages`
**認証:** `x-api-key: your_api_password` または `Authorization: Bearer your_api_password`

**リクエスト例:**
```bash
curl -X POST "http://127.0.0.1:7861/v1/messages" \
  -H "x-api-key: your_api_password" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-pro",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'
```

**systemパラメータの対応:**
```json
{
  "model": "gemini-2.5-pro",
  "max_tokens": 1024,
  "system": "You are a helpful assistant",
  "messages": [
    {"role": "user", "content": "Hello"}
  ]
}
```

**注意事項:**
- Claude APIフォーマット仕様に完全互換
- バックエンド呼び出し時にGeminiフォーマットへ自動変換
- すべてのClaude標準パラメータに対応
- レスポンスフォーマットはClaude API仕様に準拠

#### 4. Antigravity APIエンドポイント

**OpenAI、Gemini、Claudeの3フォーマットに対応**

##### Antigravity OpenAIフォーマットエンドポイント

**エンドポイント:** `/antigravity/v1/chat/completions`
**認証:** `Authorization: Bearer your_api_password`

**リクエスト例:**
```bash
curl -X POST "http://127.0.0.1:7861/antigravity/v1/chat/completions" \
  -H "Authorization: Bearer your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "messages": [
      {"role": "user", "content": "Hello"}
    ],
    "stream": true
  }'
```

##### Antigravity Geminiフォーマットエンドポイント

**非ストリーミングエンドポイント:** `/antigravity/v1/models/{model}:generateContent`
**ストリーミングエンドポイント:** `/antigravity/v1/models/{model}:streamGenerateContent`

**認証方式（いずれか1つを選択）:**
- `Authorization: Bearer your_api_password`
- `x-goog-api-key: your_api_password`
- URLパラメータ: `?key=your_api_password`

**リクエスト例:**
```bash
# Geminiフォーマット非ストリーミングリクエスト
curl -X POST "http://127.0.0.1:7861/antigravity/v1/models/claude-sonnet-4-5:generateContent" \
  -H "x-goog-api-key: your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ],
    "generationConfig": {
      "temperature": 0.7
    }
  }'

# Geminiフォーマットストリーミングリクエスト
curl -X POST "http://127.0.0.1:7861/antigravity/v1/models/gemini-2.5-flash:streamGenerateContent?key=your_api_password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"role": "user", "parts": [{"text": "Hello"}]}
    ]
  }'
```

##### Antigravity Claudeフォーマットエンドポイント

**エンドポイント:** `/antigravity/v1/messages`
**認証:** `x-api-key: your_api_password`

**リクエスト例:**
```bash
curl -X POST "http://127.0.0.1:7861/antigravity/v1/messages" \
  -H "x-api-key: your_api_password" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'
```

**対応Antigravityモデル:**
- Claudeシリーズ: `claude-sonnet-4-5`、`claude-opus-4-5` など
- Geminiシリーズ: `gemini-2.5-flash`、`gemini-2.5-pro` など
- Thinkingモデルに自動対応

**Geminiネイティブの例:**
```python
from io import BytesIO
from PIL import Image
from google.genai import Client
from google.genai.types import HttpOptions
from google.genai import types
# クライアントは環境変数 `GEMINI_API_KEY` からAPIキーを取得します。

client = Client(
            api_key="pwd",
            http_options=HttpOptions(base_url="http://127.0.0.1:7861"),
        )

prompt = (
    """
    猫を描いて
    """
)

response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents=[prompt],
    config=types.GenerateContentConfig(
        image_config=types.ImageConfig(
            aspect_ratio="16:9",
        )
    )
)
for part in response.candidates[0].content.parts:
    if part.text is not None:
        print(part.text)
    elif part.inline_data is not None:
        image = Image.open(BytesIO(part.inline_data.data))
        image.save("generated_image.png")

```

**注意事項:**
- OpenAIエンドポイントはOpenAI互換フォーマットを返します
- GeminiエンドポイントはGeminiネイティブフォーマットを返します
- 両エンドポイントとも同一のAPIパスワードを使用

## 📋 完全なAPIリファレンス

### Webコンソール API

**認証エンドポイント**
- `POST /auth/login` - ユーザーログイン
- `POST /auth/start` - OAuth認証の開始（GCLIおよびAntigravityモード対応）
- `POST /auth/callback` - OAuthコールバックの処理
- `POST /auth/callback-url` - コールバックURLから直接認証を完了
- `GET /auth/status/{project_id}` - 認証ステータスの確認

**クレデンシャル管理エンドポイント**（`mode=geminicli` または `mode=antigravity` パラメータ対応）
- `POST /creds/upload` - クレデンシャルファイルの一括アップロード（JSONおよびZIP対応）
- `GET /creds/status` - クレデンシャルステータス一覧の取得（ページネーションとフィルタリング対応）
- `GET /creds/detail/{filename}` - 単一クレデンシャルの詳細取得
- `POST /creds/action` - 単一クレデンシャル操作（有効化/無効化/削除）
- `POST /creds/batch-action` - クレデンシャルの一括操作
- `GET /creds/download/{filename}` - 単一クレデンシャルファイルのダウンロード
- `GET /creds/download-all` - 全クレデンシャルの一括ダウンロード
- `POST /creds/fetch-email/{filename}` - ユーザーメールの取得
- `POST /creds/refresh-all-emails` - ユーザーメールの一括更新
- `POST /creds/deduplicate-by-email` - メールによるクレデンシャルの重複排除
- `POST /creds/verify-project/{filename}` - クレデンシャルのProject ID検証
- `GET /creds/quota/{filename}` - クレデンシャルのクォータ情報取得（Antigravityのみ）

**設定管理エンドポイント**
- `GET /config/get` - 現在の設定の取得
- `POST /config/save` - 設定の保存

**ログ管理エンドポイント**
- `POST /logs/clear` - ログのクリア
- `GET /logs/download` - ログファイルのダウンロード
- `WebSocket /logs/stream` - リアルタイムログストリーム

**バージョン情報エンドポイント**
- `GET /version/info` - バージョン情報の取得（オプション `check_update=true` パラメータで更新確認）

### チャットAPI機能

**マルチモーダル対応**
```json
{
  "model": "gemini-2.5-pro",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "この画像を説明してください"},
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABA..."
          }
        }
      ]
    }
  ]
}
```

**Thinkingモード対応**
```json
{
  "model": "gemini-2.5-pro-high",
  "messages": [
    {"role": "user", "content": "複雑な数学の問題"}
  ]
}
```

レスポンスには分離された思考内容が含まれます:
```json
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "最終回答",
      "reasoning_content": "詳細な思考プロセス..."
    }
  }]
}
```

**ストリーミング途切れ防止の使用方法**
```json
{
  "model": "流式抗截断/gemini-2.5-pro",
  "messages": [
    {"role": "user", "content": "長い記事を書いてください"}
  ],
  "stream": true
}
```

**互換モード**
```bash
# 互換モードを有効化
export COMPATIBILITY_MODE=true
```
このモードでは、すべての `system` メッセージが `user` メッセージに変換され、特定のクライアントとの互換性が向上します。

---

## 💬 コミュニティ

QQグループへの参加をお待ちしています！

**QQグループ: 1083250744**



---

## ライセンスと免責事項

本プロジェクトは学習および研究目的のみに使用できます。本プロジェクトの使用は、以下に同意したことを意味します:
- 本プロジェクトをいかなる商用目的にも使用しないこと
- 本プロジェクトの使用に伴うすべてのリスクと責任を負うこと
- 関連するサービス利用規約および法的規制を遵守すること

プロジェクトの作者は、本プロジェクトの使用から生じるいかなる直接的または間接的な損害についても責任を負いません。

## ⚠️ ライセンスについて

**本プロジェクトはCooperative Non-Commercial License (CNC-1.0) の下でライセンスされています**

これは厳格な非商用オープンソースライセンスです。詳細は [LICENSE](../LICENSE) ファイルをご参照ください。

### ✅ 許可される用途:
- 個人の学習、研究、教育目的
- 非営利団体での利用
- オープンソースプロジェクトへの統合（同一ライセンスの遵守が必要）
- 学術研究および論文発表

### ❌ 禁止される用途:
- あらゆる形態の商用利用
- 年間売上が100万ドルを超える企業での利用
- ベンチャーキャピタルの出資を受けた企業または上場企業
- 有料サービスまたは製品の提供
- 商業的な競合利用