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

中文 | English

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

screenshot

本仓库额外提供 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

如果拉取镜像时报 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 管理、后台管理接口语义一致)。 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 下行为一致。

• 支持类型筛选: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)。

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

支持两种方式:

• 直接添加 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 文件

• 配置文件: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 账号:无账号,作者未测试

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

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":"你好"}]
 }'

图像生成接口

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
 }'

返回当前生图后端方式(/chat 与 /admin/chat 用于判断是否启用"新生图瀑布流 + 宽高比 + 并发")

curl http://localhost:8000/v1/images/method \
 -H "Authorization: Bearer $GROK2API_API_KEY"

返回示例:

{ "image_generation_method": "legacy" }

• 可选值:legacy、imagine_ws_experimental
• Cloudflare / Docker / 本地 三种部署均保持同一接口语义

• In experimental mode, the image panel is replaced and supports two run modes: single and continuous.
• single keeps using POST /v1/images/generations and remains response-compatible.
• continuous uses WebSocket: /api/v1/admin/imagine/ws?api_key=<API_KEY>.
• WS commands: start / stop / ping.
• WS events: status / image / error / pong.
• Continuous payload includes b64_json, sequence, elapsed_ms, aspect_ratio, run_id.

图像编辑接口(multipart/form-data)

curl http://localhost:8000/v1/images/edits \
 -H "Authorization: Bearer $GROK2API_API_KEY" \
 -F "model=grok-imagine-1.0-edit" \
 -F "prompt=给这只猫加一副太阳镜" \
 -F "image=@./cat.png" \
 -F "n=1" \
 -F "response_format=url"

1. GET /api/v1/admin/tokens(增量兼容,保留旧字段)新增:
   • token_type
   • quota_known
   • heavy_quota
   • heavy_quota_known
2. POST /api/v1/admin/keys/update:
   • 当 key 不存在时返回 404(此前部分实现可能返回成功)。
3. 额度语义补充:
   • quota_known = false 表示额度未知(例如 remaining_queries = -1 场景),不应直接判定为"额度用尽"。

配置文件:data/config.toml

当你从旧版本升级到当前版本时,程序会在启动时自动兼容并读取旧数据:

• 旧配置:若存在 data/setting.toml,会自动迁移/合并到 data/config.toml(仅覆盖"缺失项"或"仍为默认值"的字段)。
• 旧缓存目录:旧版 data/temp/{image,video} 会自动迁移到新版 data/tmp/{image,video},未到清理时间的缓存文件不会丢失。
• Docker 部署:务必持久化挂载 ./data:/app/data(以及 ./logs:/app/logs),否则容器更新/重建会丢失本地数据。

• 修复 Token 页 refreshStatus 依赖全局 event 的问题,改为显式传入按钮引用,避免不同运行环境下按钮状态异常。
• 新增 Token 统一归一化(normalizeSsoToken),修复 sso= 前缀导致的去重、导入、批量选择不一致问题。
• 修复 API Key 更新接口"key 不存在仍返回成功"问题,统一为 404。
• 优化 Token/API Key 页面错误提示,优先展示后端具体错误(detail/error/message)。

• 新增:导入/手动添加/外部写入新增 Token 后,会在后台自动执行 同意协议 + 设置年龄 + 开启 NSFW。
• 新增:Token 管理页增加「一键刷新 NSFW」按钮,默认对全部 Token 执行上述流程。
• 新增:批量刷新默认并发 10,失败后额外重试 3 次;重试耗尽自动标记为失效。
• 新增配置:
  • token.nsfw_refresh_concurrency(默认 10)
  • token.nsfw_refresh_retries(默认 3)
• 说明:该功能仅在 python-fastapi(本地/Docker)开放;cloudflare-workers 侧不展示该按钮。

Star History Chart