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

中文 | English

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

本仓库额外提供 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 侧不展示该按钮。