Grok2API

本项目为对 chenyme/grok2api 的二次修改与增强。

中文 | English

[!NOTE] 本项目仅供学习与研究，使用者必须在遵循 Grok 的 使用条款 以及 法律法规 的情况下使用，不得用于非法用途。

基于 FastAPI 重构的 Grok2API，全面适配最新 Web 调用格式，支持流/非流式对话、图像生成/编辑、深度思考，号池并发与自动负载均衡一体化。

Cloudflare Workers / Pages（Fork 增强）

本仓库额外提供 Cloudflare Workers / Pages（TypeScript，D1 + KV）版本，适合在 Cloudflare 上运行与代理出站。

部署与配置说明：README.cloudflare.md
一键部署工作流：.github/workflows/cloudflare-workers.yml
- 一键部署前置条件：仓库需配置 CLOUDFLARE_API_TOKEN 与 CLOUDFLARE_ACCOUNT_ID。

使用说明

如何启动

本地开发

uv sync

uv run main.py

# （可选）启动后自检
python scripts/smoke_test.py --base-url http://127.0.0.1:8000

项目部署

git clone https://github.com/TQZHR/grok2api.git

# 进入项目目录
cd grok2api

# 直接拉取镜像启动（默认）
docker compose up -d

# 更新到最新镜像
docker compose pull
docker compose up -d

# 从当前仓库源码构建并启动（可选）
docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

# （可选）启动后自检
python scripts/smoke_test.py --base-url http://127.0.0.1:8000

仓库级部署自检

在执行一键部署前，建议先在仓库根目录运行：

uv run pytest -q
npm run typecheck
python scripts/check_model_catalog_sync.py
npx wrangler deploy --dry-run --config wrangler.toml
docker compose -f docker-compose.yml config
docker compose -f docker-compose.yml -f docker-compose.build.yml config

如果拉取镜像时报 denied：说明 GHCR 镜像不可匿名拉取（未公开或需要登录）。你可以先执行 docker login ghcr.io，或在 .env 里设置 GROK2API_IMAGE 指向你自己的公开镜像；也可以用上面的 --build 从源码构建运行。

可选：复制 .env.example 为 .env，可配置端口/日志/存储等；并可通过 COMPOSE_PROFILES 一键启用 redis/pgsql/mysql（见 .env.example 内示例）。

部署一致性说明：本地（FastAPI）/ Docker / Cloudflare Workers 共用同一套管理功能语义（Token 筛选、API Key 管理、后台管理接口语义一致）。上游关键同步（2026-02-20）：已同步聊天页“重试上一条回答”与“图片加载失败点击重试”，三部署下行为一致。 Cloudflare 可通过 .github/workflows/cloudflare-workers.yml 一键部署（需先配置上述两个 Secrets），Docker 仍保持 docker compose up -d 一键启动。

管理面板

访问地址：http://<host>:8000/login

默认账号密码：admin / admin（对应配置项 app.admin_username / app.app_key，建议上线后修改）。

常用页面：

http://<host>:8000/admin/token：Token 管理（导入/导出/批量操作/自动注册）
http://<host>:8000/admin/keys：API Key 管理（统计/筛选/新增/编辑/删除）
http://<host>:8000/admin/datacenter：数据中心（常用指标 + 日志查看）
http://<host>:8000/admin/config：配置管理（含自动注册所需配置）
http://<host>:8000/admin/cache：缓存管理（本地缓存 + 在线资产）

手机端适配（全站）

已覆盖页面：/login、/admin/token、/admin/keys、/admin/cache、/admin/config、/admin/datacenter、/chat、/admin/chat。
后台顶部导航在手机端改为抽屉菜单（支持：打开/关闭、点击遮罩关闭、点击菜单项后自动收起、Esc 关闭）。
表格在手机端保持“横向滚动优先”，不压缩列结构（Token/API Key/缓存表格行为一致）。
Toast 在窄屏改为左右边距自适应，不再固定最小宽度导致溢出。
底部批量操作条（Token/缓存）在手机端改为全宽底部卡片样式，减少遮挡主操作。
三部署一致性：上述适配使用同一套静态资源，在本地 FastAPI / Docker / Cloudflare Workers 下行为一致。

Token 管理增强（筛选 + 状态判定）

支持类型筛选：sso、supersso（可组合）。
支持状态筛选：活跃、失效、额度用尽（可组合，按并集语义）。
提供“结果计数”和“清空筛选”。
筛选后勾选/全选/批量刷新/批量删除均基于 Token 唯一值，避免过滤后行索引错位导致误操作。
状态判定规则：
- 失效：status 为 invalid/expired/disabled
- 额度用尽：status = cooling，或（quota_known = true 且 quota <= 0），或（super 且 heavy_quota_known = true 且 heavy_quota <= 0）
- 活跃：非失效且非额度用尽
类型映射规则：ssoBasic -> sso，ssoSuper -> supersso（接口字段 token_type 为 sso / ssoSuper）。

API Key 管理增强

页面新增统计卡片：总数、启用、禁用、今日额度用尽。
工具栏支持：名称/Key 搜索、状态筛选（全部/启用/禁用/额度用尽）、重置筛选。
新增 API Key 弹窗增强：
- 居中悬浮弹窗（遮罩层 + 缩放入场动画）
- 支持点击遮罩关闭、Esc 关闭
- 移动端弹窗内容可滚动且网格布局自适应
- 自动生成 Key
- 额度预设（推荐/不限）
- 提交中禁用按钮，防止重复提交
- 创建成功后支持一键复制 Key
错误提示优化：前端优先展示后端 detail/error/message，避免“创建失败/更新失败”无上下文。
更新不存在的 Key 会返回 404（FastAPI 与 Workers 一致）。

自动注册（Token 管理 -> 添加 -> 自动注册）

支持两种方式：

直接添加 Token（手动/批量导入）
自动注册并自动写入 Token 池

自动注册特性：

可设置注册数量（不填默认 100）
可设置并发（默认 10）
注册前会自动启动本地 Turnstile Solver（默认 5 线程），注册结束后自动关闭
注册成功后会自动执行：同意用户协议（TOS）+ 设置年龄 + 开启 NSFW
- 若 TOS / 年龄 / NSFW 任一步骤失败，会判定该次注册失败并在前端显示错误原因

自动注册前置配置（在「配置管理」-> register.*）：

register.worker_domain / register.email_domain / register.admin_password：临时邮箱 Worker 配置
register.solver_url / register.solver_browser_type / register.solver_threads：本地 Turnstile Solver 配置
可选：register.yescaptcha_key（配置后优先走 YesCaptcha，无需本地 solver）

升级兼容：

本地部署升级后会自动对「旧 Token」做一次 TOS + 设置年龄 + NSFW（并发 10，best-effort，仅执行一次，避免重复刷）。

环境变量

配置 .env 文件

| 变量名 | 说明 | 默认值 | 示例 | | :---------------------- | :-------------------------------------------------- | :---------- | :-------------------------------------------------- | | LOG_LEVEL | 日志级别 | INFO | DEBUG | | SERVER_HOST | 服务监听地址 | 0.0.0.0 | 0.0.0.0 | | SERVER_PORT | 服务端口 | 8000 | 8000 | | SERVER_WORKERS | Uvicorn worker 数量 | 1 | 2 | | SERVER_STORAGE_TYPE | 存储类型（local/redis/mysql/pgsql） | local | pgsql | | SERVER_STORAGE_URL | 存储连接串（local 时可为空） | "" | postgresql+asyncpg://user:password@host:5432/db |

配置文件与升级迁移

配置文件：data/config.toml（首次启动会基于 config.defaults.toml 自动生成；管理面板也可直接修改）
Token 数据：data/token.json
升级时自动兼容迁移（本地/Docker）：
- 旧版配置：检测到 data/setting.toml 时，会按“缺失字段/仍为默认值”的策略合并到新配置
- 旧版缓存目录：data/temp/{image,video} -> data/tmp/{image,video}
- 旧账号一次性修复（best-effort）：升级后会对现有 Token 自动执行一次「同意用户协议 + 设置年龄 + 开启 NSFW」（并发 10）

可用次数

Basic 账号：80 次 / 20h
Super 账号：无账号，作者未测试

可用模型

| 模型名 | 计次 | 可用账号 | 对话功能 | 图像功能 | 视频功能 | | :------------------------- | :--: | :---------- | :------: | :------: | :------: | | grok-3 | 1 | Basic/Super | 支持 | 支持 | - | | grok-3-mini | 1 | Basic/Super | 支持 | 支持 | - | | grok-3-thinking | 1 | Basic/Super | 支持 | 支持 | - | | grok-4 | 1 | Basic/Super | 支持 | 支持 | - | | grok-4-mini | 1 | Basic/Super | 支持 | 支持 | - | | grok-4-thinking | 1 | Basic/Super | 支持 | 支持 | - | | grok-4-heavy | 4 | Super | 支持 | 支持 | - | | grok-4.1-mini | 1 | Basic/Super | 支持 | 支持 | - | | grok-4.1-fast | 1 | Basic/Super | 支持 | 支持 | - | | grok-4.1-expert | 4 | Basic/Super | 支持 | 支持 | - | | grok-4.1-thinking | 4 | Basic/Super | 支持 | 支持 | - | | grok-4.20-beta | 1 | Basic/Super | 支持 | 支持 | - | | grok-imagine-1.0 | - | Basic/Super | - | 支持 | - | | grok-imagine-1.0-edit | - | Basic/Super | - | 支持 | - | | grok-imagine-1.0-video | - | Basic/Super | - | - | 支持 |

接口说明

`POST /v1/chat/completions`

通用接口，支持对话聊天、图像生成、图像编辑、视频生成、视频超分

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-4",
    "messages": [{"role":"user","content":"你好"}]
  }'

<details> <summary>支持的请求参数</summary>

注：除上述外的其他参数将自动丢弃并忽略

</details>

`POST /v1/images/generations`

图像生成接口

curl http://localhost:8000/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GROK2API_API_KEY" \
  -d '{
    "model": "grok-imagine-1.0",
    "prompt": "一只在太空漂浮的猫",
    "n": 1
  }'